@lucern/contracts 0.1.2-alpha.5 → 0.3.0-alpha.0

package/dist/function-registry/coordination.d.ts

@@ -0,0 +1,476 @@
+import * as zod from 'zod';
+
+/**
+ * MCP Tool Contract Definitions
+ *
+ * Machine-readable source of truth for all Lucern MCP tool names,
+ * descriptions, parameters, and response schemas.
+ *
+ * CONTRACT SURFACE: These definitions are the external API for AI agents.
+ * Renaming a tool or changing its description is a BREAKING CHANGE.
+ *
+ * Git-native naming rules (enforced by lint):
+ *   1. Workflow tools use git verbs directly (add_worktree, merge, push, open_pull_request)
+ *   2. Knowledge tools use epistemic verbs (create_belief, fork_belief, modulate_confidence)
+ *   3. First sentence of description includes the git analog verb
+ *   4. Description includes "Like `git X`" parenthetical
+ *   5. Parameter names use domain terms (canonicalText, nodeId, confidence)
+ */
+type McpToolContract = {
+    /** Stable tool name — breaking change to rename */
+    name: string;
+    /** Git-semantic description — breaking change to remove git references */
+    description: string;
+    /** Parameter schema (JSON Schema subset) */
+    parameters: Record<string, McpParameterDef>;
+    /** Required parameter names */
+    required: string[];
+    /** Response shape description */
+    response: McpResponseDef;
+    /** Which Lucern module owns the implementation */
+    ownerModule: string;
+    /** Ontology primitive this tool operates on */
+    ontologyPrimitive: "belief" | "evidence" | "source" | "question" | "judgment" | "worktree" | "branch" | "lens" | "edge" | "graph" | "task" | "policy" | "ontology" | "identity";
+    /** MCP surface tier — showcase (front page, every demo) or workhorse (complete CRUD, discovered when building) */
+    tier: "showcase" | "workhorse";
+    /** Hide this tool from public discovery surfaces. */
+    internal?: boolean;
+    /** Deprecation notice shown in contract-driven docs and discovery. */
+    deprecated?: string;
+};
+type McpParameterDef = {
+    type: "string" | "number" | "boolean" | "array" | "object";
+    description: string;
+    required?: boolean;
+    enum?: string[];
+};
+type McpResponseDef = {
+    description: string;
+    fields: Record<string, string>;
+};
+
+type FunctionEffect = "read" | "write" | "admin";
+
+type FunctionKind = "query" | "mutation" | "action";
+type FunctionIdempotency = boolean | "required";
+type FunctionSurfaceIntent = "mcp_core" | "mcp_analysis" | "mcp_workflow" | "mcp_governance" | "system" | "compatibility" | "sdk_granular";
+type SurfaceClass = "platform_public" | "tenant_public" | "platform_internal" | "legacy_compat" | "application_tool" | "external_connector";
+type SurfaceExposure = "public" | "internal" | "none";
+type FunctionSurfaceMap = {
+    sdk: SurfaceExposure;
+    rest: SurfaceExposure;
+    mcp: SurfaceExposure;
+    cli: SurfaceExposure;
+};
+type ContractProjectionContext = {
+    tenantId?: string;
+    workspaceId?: string;
+    userId?: string;
+    principalId?: string;
+    correlationId?: string;
+    policyTraceId?: string;
+    idempotencyKey?: string;
+};
+type ContractInputProjection = (input: Record<string, unknown>, context: ContractProjectionContext) => Record<string, unknown>;
+type ContractOutputProjection = (output: unknown, input: Record<string, unknown>, context: ContractProjectionContext) => unknown;
+type FunctionConvexTarget = {
+    module: string;
+    functionName: string;
+    kind: FunctionKind;
+    injectSessionId?: "sessionId" | "fromSessionId";
+    injectSessionContext?: boolean;
+    broadcastToAll?: boolean;
+    inputProjection?: ContractInputProjection;
+    outputProjection?: ContractOutputProjection;
+};
+
+declare const coordinationContracts: readonly [{
+    name: string;
+    kind: FunctionKind;
+    idempotent: FunctionIdempotency;
+    effects: readonly FunctionEffect[];
+    invariants: readonly string[] | undefined;
+    surfaceIntent: FunctionSurfaceIntent;
+    domain: string;
+    surfaceClass: SurfaceClass;
+    surfaces: FunctionSurfaceMap;
+    replacedBy: string | undefined;
+    rest: {
+        method: "GET" | "POST" | "PATCH" | "DELETE";
+        path: string;
+    };
+    sdk: {
+        namespace: string;
+        method: string;
+    };
+    mcp: {
+        exposed: boolean;
+        toolName: string;
+    } & McpToolContract & {
+        exposed: boolean;
+        toolName: string;
+    };
+    auth: {
+        scopes: string[];
+        allowedPrincipalTypes: ("user" | "service" | "agent")[];
+    };
+    convex: FunctionConvexTarget | undefined;
+    args: zod.ZodObject<zod.ZodRawShape, zod.UnknownKeysParam, zod.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>;
+    returns: zod.ZodTypeAny;
+    input: zod.ZodTypeAny;
+    output: zod.ZodTypeAny;
+    openapi: {
+        summary: string;
+        tags: string[];
+    };
+}, {
+    name: string;
+    kind: FunctionKind;
+    idempotent: FunctionIdempotency;
+    effects: readonly FunctionEffect[];
+    invariants: readonly string[] | undefined;
+    surfaceIntent: FunctionSurfaceIntent;
+    domain: string;
+    surfaceClass: SurfaceClass;
+    surfaces: FunctionSurfaceMap;
+    replacedBy: string | undefined;
+    rest: {
+        method: "GET" | "POST" | "PATCH" | "DELETE";
+        path: string;
+    };
+    sdk: {
+        namespace: string;
+        method: string;
+    };
+    mcp: {
+        exposed: boolean;
+        toolName: string;
+    } & McpToolContract & {
+        exposed: boolean;
+        toolName: string;
+    };
+    auth: {
+        scopes: string[];
+        allowedPrincipalTypes: ("user" | "service" | "agent")[];
+    };
+    convex: FunctionConvexTarget | undefined;
+    args: zod.ZodObject<zod.ZodRawShape, zod.UnknownKeysParam, zod.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>;
+    returns: zod.ZodTypeAny;
+    input: zod.ZodTypeAny;
+    output: zod.ZodTypeAny;
+    openapi: {
+        summary: string;
+        tags: string[];
+    };
+}, {
+    name: string;
+    kind: FunctionKind;
+    idempotent: FunctionIdempotency;
+    effects: readonly FunctionEffect[];
+    invariants: readonly string[] | undefined;
+    surfaceIntent: FunctionSurfaceIntent;
+    domain: string;
+    surfaceClass: SurfaceClass;
+    surfaces: FunctionSurfaceMap;
+    replacedBy: string | undefined;
+    rest: {
+        method: "GET" | "POST" | "PATCH" | "DELETE";
+        path: string;
+    };
+    sdk: {
+        namespace: string;
+        method: string;
+    };
+    mcp: {
+        exposed: boolean;
+        toolName: string;
+    } & McpToolContract & {
+        exposed: boolean;
+        toolName: string;
+    };
+    auth: {
+        scopes: string[];
+        allowedPrincipalTypes: ("user" | "service" | "agent")[];
+    };
+    convex: FunctionConvexTarget | undefined;
+    args: zod.ZodObject<zod.ZodRawShape, zod.UnknownKeysParam, zod.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>;
+    returns: zod.ZodTypeAny;
+    input: zod.ZodTypeAny;
+    output: zod.ZodTypeAny;
+    openapi: {
+        summary: string;
+        tags: string[];
+    };
+}, {
+    name: string;
+    kind: FunctionKind;
+    idempotent: FunctionIdempotency;
+    effects: readonly FunctionEffect[];
+    invariants: readonly string[] | undefined;
+    surfaceIntent: FunctionSurfaceIntent;
+    domain: string;
+    surfaceClass: SurfaceClass;
+    surfaces: FunctionSurfaceMap;
+    replacedBy: string | undefined;
+    rest: {
+        method: "GET" | "POST" | "PATCH" | "DELETE";
+        path: string;
+    };
+    sdk: {
+        namespace: string;
+        method: string;
+    };
+    mcp: {
+        exposed: boolean;
+        toolName: string;
+    } & McpToolContract & {
+        exposed: boolean;
+        toolName: string;
+    };
+    auth: {
+        scopes: string[];
+        allowedPrincipalTypes: ("user" | "service" | "agent")[];
+    };
+    convex: FunctionConvexTarget | undefined;
+    args: zod.ZodObject<zod.ZodRawShape, zod.UnknownKeysParam, zod.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>;
+    returns: zod.ZodTypeAny;
+    input: zod.ZodTypeAny;
+    output: zod.ZodTypeAny;
+    openapi: {
+        summary: string;
+        tags: string[];
+    };
+}, {
+    name: string;
+    kind: FunctionKind;
+    idempotent: FunctionIdempotency;
+    effects: readonly FunctionEffect[];
+    invariants: readonly string[] | undefined;
+    surfaceIntent: FunctionSurfaceIntent;
+    domain: string;
+    surfaceClass: SurfaceClass;
+    surfaces: FunctionSurfaceMap;
+    replacedBy: string | undefined;
+    rest: {
+        method: "GET" | "POST" | "PATCH" | "DELETE";
+        path: string;
+    };
+    sdk: {
+        namespace: string;
+        method: string;
+    };
+    mcp: {
+        exposed: boolean;
+        toolName: string;
+    } & McpToolContract & {
+        exposed: boolean;
+        toolName: string;
+    };
+    auth: {
+        scopes: string[];
+        allowedPrincipalTypes: ("user" | "service" | "agent")[];
+    };
+    convex: FunctionConvexTarget | undefined;
+    args: zod.ZodObject<zod.ZodRawShape, zod.UnknownKeysParam, zod.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>;
+    returns: zod.ZodTypeAny;
+    input: zod.ZodTypeAny;
+    output: zod.ZodTypeAny;
+    openapi: {
+        summary: string;
+        tags: string[];
+    };
+}, {
+    name: string;
+    kind: FunctionKind;
+    idempotent: FunctionIdempotency;
+    effects: readonly FunctionEffect[];
+    invariants: readonly string[] | undefined;
+    surfaceIntent: FunctionSurfaceIntent;
+    domain: string;
+    surfaceClass: SurfaceClass;
+    surfaces: FunctionSurfaceMap;
+    replacedBy: string | undefined;
+    rest: {
+        method: "GET" | "POST" | "PATCH" | "DELETE";
+        path: string;
+    };
+    sdk: {
+        namespace: string;
+        method: string;
+    };
+    mcp: {
+        exposed: boolean;
+        toolName: string;
+    } & McpToolContract & {
+        exposed: boolean;
+        toolName: string;
+    };
+    auth: {
+        scopes: string[];
+        allowedPrincipalTypes: ("user" | "service" | "agent")[];
+    };
+    convex: FunctionConvexTarget | undefined;
+    args: zod.ZodObject<zod.ZodRawShape, zod.UnknownKeysParam, zod.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>;
+    returns: zod.ZodTypeAny;
+    input: zod.ZodTypeAny;
+    output: zod.ZodTypeAny;
+    openapi: {
+        summary: string;
+        tags: string[];
+    };
+}, {
+    name: string;
+    kind: FunctionKind;
+    idempotent: FunctionIdempotency;
+    effects: readonly FunctionEffect[];
+    invariants: readonly string[] | undefined;
+    surfaceIntent: FunctionSurfaceIntent;
+    domain: string;
+    surfaceClass: SurfaceClass;
+    surfaces: FunctionSurfaceMap;
+    replacedBy: string | undefined;
+    rest: {
+        method: "GET" | "POST" | "PATCH" | "DELETE";
+        path: string;
+    };
+    sdk: {
+        namespace: string;
+        method: string;
+    };
+    mcp: {
+        exposed: boolean;
+        toolName: string;
+    } & McpToolContract & {
+        exposed: boolean;
+        toolName: string;
+    };
+    auth: {
+        scopes: string[];
+        allowedPrincipalTypes: ("user" | "service" | "agent")[];
+    };
+    convex: FunctionConvexTarget | undefined;
+    args: zod.ZodObject<zod.ZodRawShape, zod.UnknownKeysParam, zod.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>;
+    returns: zod.ZodTypeAny;
+    input: zod.ZodTypeAny;
+    output: zod.ZodTypeAny;
+    openapi: {
+        summary: string;
+        tags: string[];
+    };
+}, {
+    name: string;
+    kind: FunctionKind;
+    idempotent: FunctionIdempotency;
+    effects: readonly FunctionEffect[];
+    invariants: readonly string[] | undefined;
+    surfaceIntent: FunctionSurfaceIntent;
+    domain: string;
+    surfaceClass: SurfaceClass;
+    surfaces: FunctionSurfaceMap;
+    replacedBy: string | undefined;
+    rest: {
+        method: "GET" | "POST" | "PATCH" | "DELETE";
+        path: string;
+    };
+    sdk: {
+        namespace: string;
+        method: string;
+    };
+    mcp: {
+        exposed: boolean;
+        toolName: string;
+    } & McpToolContract & {
+        exposed: boolean;
+        toolName: string;
+    };
+    auth: {
+        scopes: string[];
+        allowedPrincipalTypes: ("user" | "service" | "agent")[];
+    };
+    convex: FunctionConvexTarget | undefined;
+    args: zod.ZodObject<zod.ZodRawShape, zod.UnknownKeysParam, zod.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>;
+    returns: zod.ZodTypeAny;
+    input: zod.ZodTypeAny;
+    output: zod.ZodTypeAny;
+    openapi: {
+        summary: string;
+        tags: string[];
+    };
+}, {
+    name: string;
+    kind: FunctionKind;
+    idempotent: FunctionIdempotency;
+    effects: readonly FunctionEffect[];
+    invariants: readonly string[] | undefined;
+    surfaceIntent: FunctionSurfaceIntent;
+    domain: string;
+    surfaceClass: SurfaceClass;
+    surfaces: FunctionSurfaceMap;
+    replacedBy: string | undefined;
+    rest: {
+        method: "GET" | "POST" | "PATCH" | "DELETE";
+        path: string;
+    };
+    sdk: {
+        namespace: string;
+        method: string;
+    };
+    mcp: {
+        exposed: boolean;
+        toolName: string;
+    } & McpToolContract & {
+        exposed: boolean;
+        toolName: string;
+    };
+    auth: {
+        scopes: string[];
+        allowedPrincipalTypes: ("user" | "service" | "agent")[];
+    };
+    convex: FunctionConvexTarget | undefined;
+    args: zod.ZodObject<zod.ZodRawShape, zod.UnknownKeysParam, zod.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>;
+    returns: zod.ZodTypeAny;
+    input: zod.ZodTypeAny;
+    output: zod.ZodTypeAny;
+    openapi: {
+        summary: string;
+        tags: string[];
+    };
+}];
+
+export { coordinationContracts };