@lucern/sdk 0.2.0-alpha.7 → 0.2.0-alpha.9

package/dist/customTools.js

@@ -0,0 +1,248 @@
+import { z } from 'zod';
+
+// src/customTools.ts
+var DEFAULT_CUSTOM_NAMESPACE = "custom";
+var RESERVED_NAMESPACES = /* @__PURE__ */ new Set(["lucern"]);
+var CustomToolRegistryError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CustomToolRegistryError";
+  }
+};
+var customToolRegistry = /* @__PURE__ */ new Map();
+function normalizeSegment(value, field) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new CustomToolRegistryError(`Custom tool ${field} is required.`);
+  }
+  if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(normalized)) {
+    throw new CustomToolRegistryError(
+      `Invalid custom tool ${field}: "${value}". Use letters, numbers, "_" or "-".`
+    );
+  }
+  return normalized;
+}
+function normalizeNamespace(namespace) {
+  const resolved = normalizeSegment(
+    namespace ?? DEFAULT_CUSTOM_NAMESPACE,
+    "namespace"
+  );
+  if (RESERVED_NAMESPACES.has(resolved.toLowerCase())) {
+    throw new CustomToolRegistryError(
+      `Namespace "${resolved}" is reserved for platform tools.`
+    );
+  }
+  return resolved;
+}
+function normalizeName(name) {
+  if (name.includes(".")) {
+    throw new CustomToolRegistryError(
+      `Custom tool name "${name}" must not include "."; use namespace + name.`
+    );
+  }
+  return normalizeSegment(name, "name");
+}
+function buildFullName(namespace, shortName) {
+  return `${namespace}.${shortName}`;
+}
+function unwrapSchema(schema) {
+  if (schema instanceof z.ZodOptional) {
+    return { schema: schema.unwrap(), required: false };
+  }
+  if (schema instanceof z.ZodDefault) {
+    const removeDefault = schema.removeDefault;
+    if (typeof removeDefault === "function") {
+      return { schema: removeDefault.call(schema), required: false };
+    }
+    const inner = schema._def?.innerType;
+    return { schema: inner ?? schema, required: false };
+  }
+  return { schema, required: true };
+}
+function resolveParameterType(schema) {
+  if (schema instanceof z.ZodString) {
+    return { type: "string" };
+  }
+  if (schema instanceof z.ZodEnum) {
+    return { type: "string", enum: schema.options };
+  }
+  if (schema instanceof z.ZodNativeEnum) {
+    const values = Object.values(schema.enum).filter(
+      (value) => typeof value === "string"
+    );
+    return values.length > 0 ? { type: "string", enum: values } : { type: "string" };
+  }
+  if (schema instanceof z.ZodLiteral) {
+    const literalValue = schema.value;
+    if (typeof literalValue === "string") {
+      return { type: "string", enum: [literalValue] };
+    }
+    if (typeof literalValue === "number") {
+      return { type: "number" };
+    }
+    if (typeof literalValue === "boolean") {
+      return { type: "boolean" };
+    }
+    return { type: "object" };
+  }
+  if (schema instanceof z.ZodNumber) {
+    return { type: "number" };
+  }
+  if (schema instanceof z.ZodBoolean) {
+    return { type: "boolean" };
+  }
+  if (schema instanceof z.ZodArray) {
+    return { type: "array" };
+  }
+  return { type: "object" };
+}
+function schemaTypeLabel(schema) {
+  if (schema instanceof z.ZodString || schema instanceof z.ZodEnum) {
+    return "string";
+  }
+  if (schema instanceof z.ZodNumber) {
+    return "number";
+  }
+  if (schema instanceof z.ZodBoolean) {
+    return "boolean";
+  }
+  if (schema instanceof z.ZodArray) {
+    return "array";
+  }
+  if (schema instanceof z.ZodObject) {
+    return "object";
+  }
+  return "unknown";
+}
+function parseObjectSchema(value, fieldName) {
+  if (!(value instanceof z.ZodObject)) {
+    throw new CustomToolRegistryError(
+      `${fieldName} must be a Zod object schema.`
+    );
+  }
+  return value;
+}
+function deriveParameters(schema) {
+  const shape = schema.shape;
+  const parameters = {};
+  const required = [];
+  for (const [key, raw] of Object.entries(shape)) {
+    const { schema: unwrapped, required: isRequired } = unwrapSchema(
+      raw
+    );
+    const parameterType = resolveParameterType(unwrapped);
+    parameters[key] = {
+      type: parameterType.type,
+      description: raw.description ?? `${key} parameter`,
+      ...parameterType.enum ? { enum: parameterType.enum } : {}
+    };
+    if (isRequired) {
+      required.push(key);
+    }
+  }
+  return { parameters, required };
+}
+function deriveResponse(schema) {
+  if (schema instanceof z.ZodObject) {
+    const fields = Object.fromEntries(
+      Object.entries(schema.shape).map(([key, value]) => {
+        const zodValue = value;
+        const label = schemaTypeLabel(unwrapSchema(zodValue).schema);
+        const description = zodValue.description ?? "custom output field";
+        return [key, `${label} \u2014 ${description}`];
+      })
+    );
+    return {
+      description: "Custom tool result payload",
+      fields
+    };
+  }
+  return {
+    description: "Custom tool result payload",
+    fields: {
+      result: `${schemaTypeLabel(schema)} \u2014 custom output payload`
+    }
+  };
+}
+function buildContract(fullName, namespace, registration, inputSchema) {
+  const { parameters, required } = deriveParameters(inputSchema);
+  return {
+    name: fullName,
+    description: registration.description,
+    parameters,
+    required,
+    response: deriveResponse(registration.outputSchema),
+    ownerModule: registration.ownerModule ?? `${namespace}-extension`,
+    ontologyPrimitive: registration.ontologyPrimitive ?? "task",
+    tier: registration.tier ?? "workhorse"
+  };
+}
+function registerCustomTool(registration, options = {}) {
+  const namespace = normalizeNamespace(registration.namespace);
+  const shortName = normalizeName(registration.name);
+  const fullName = buildFullName(namespace, shortName);
+  if (customToolRegistry.has(fullName) && !options.replace) {
+    throw new CustomToolRegistryError(
+      `Custom tool "${fullName}" is already registered.`
+    );
+  }
+  const inputSchema = parseObjectSchema(
+    registration.inputSchema,
+    "inputSchema"
+  );
+  const outputSchema = registration.outputSchema;
+  const contract = buildContract(
+    fullName,
+    namespace,
+    registration,
+    inputSchema
+  );
+  const metadata = {
+    category: registration.metadata?.category,
+    tags: registration.metadata?.tags ?? [],
+    requiredScopes: registration.metadata?.requiredScopes ?? ["custom:execute"]
+  };
+  const registered = {
+    fullName,
+    namespace,
+    shortName,
+    metadata,
+    contract,
+    inputSchema,
+    outputSchema,
+    invoke: async (input, context) => {
+      const parsedInput = inputSchema.parse(input);
+      const rawOutput = await registration.handler(parsedInput, context);
+      return outputSchema.parse(rawOutput);
+    }
+  };
+  customToolRegistry.set(fullName, registered);
+  return registered;
+}
+function unregisterCustomTool(fullName) {
+  return customToolRegistry.delete(fullName.trim());
+}
+function getRegisteredCustomTool(fullName) {
+  return customToolRegistry.get(fullName.trim());
+}
+function listRegisteredCustomTools() {
+  return [...customToolRegistry.values()].sort(
+    (left, right) => left.fullName.localeCompare(right.fullName)
+  );
+}
+function clearRegisteredCustomTools() {
+  customToolRegistry.clear();
+}
+async function invokeRegisteredCustomTool(fullName, params, context) {
+  const registered = getRegisteredCustomTool(fullName);
+  if (!registered) {
+    throw new CustomToolRegistryError(
+      `Custom tool "${fullName}" is not registered.`
+    );
+  }
+  return registered.invoke(params, context);
+}
+
+export { CustomToolRegistryError, clearRegisteredCustomTools, getRegisteredCustomTool, invokeRegisteredCustomTool, listRegisteredCustomTools, registerCustomTool, unregisterCustomTool };
+//# sourceMappingURL=customTools.js.map
+//# sourceMappingURL=customTools.js.map

package/dist/customTools.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/customTools.ts"],"names":[],"mappings":"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","file":"customTools.js","sourcesContent":["import { z } from \"zod\";\nimport type {\n  McpParameterDef,\n  McpResponseDef,\n  McpToolContract,\n} from \"./contracts/mcpTools\";\nimport type { JsonObject } from \"./types\";\n\n/** Default namespace assigned to custom tools when none is specified. */\nconst DEFAULT_CUSTOM_NAMESPACE = \"custom\";\n\n/** Namespace strings reserved for platform-internal tools. */\nconst RESERVED_NAMESPACES = new Set([\"lucern\"]);\n\ntype AnyZodObject = z.ZodObject<z.ZodRawShape>;\n\n/** Origin of a custom tool invocation (SDK call or MCP request). */\nexport type CustomToolInvocationSource = \"sdk\" | \"mcp\";\n\n/** Runtime context passed to a custom tool handler during invocation. */\nexport type CustomToolInvocationContext = {\n  source: CustomToolInvocationSource;\n};\n\n/** Optional metadata attached to a custom tool registration. */\nexport type CustomToolMetadata = {\n  category?: string;\n  tags?: string[];\n  requiredScopes?: string[];\n};\n\n/** Input descriptor for registering a custom tool with its schemas and handler. */\nexport type CustomToolRegistration<\n  TInput extends AnyZodObject = AnyZodObject,\n  TOutput extends z.ZodTypeAny = z.ZodTypeAny,\n> = {\n  namespace?: string;\n  name: string;\n  description: string;\n  inputSchema: TInput;\n  outputSchema: TOutput;\n  handler: (\n    input: z.infer<TInput>,\n    context: CustomToolInvocationContext\n  ) => Promise<z.infer<TOutput>> | z.infer<TOutput>;\n  metadata?: CustomToolMetadata;\n  ownerModule?: string;\n  ontologyPrimitive?: McpToolContract[\"ontologyPrimitive\"];\n  tier?: McpToolContract[\"tier\"];\n};\n\n/** A fully resolved custom tool entry stored in the in-memory registry. */\nexport type RegisteredCustomTool = {\n  fullName: string;\n  namespace: string;\n  shortName: string;\n  metadata: CustomToolMetadata;\n  contract: McpToolContract;\n  inputSchema: AnyZodObject;\n  outputSchema: z.ZodTypeAny;\n  invoke: (\n    input: JsonObject,\n    context: CustomToolInvocationContext\n  ) => Promise<unknown>;\n};\n\n/** Error thrown when custom tool registration or invocation fails validation. */\nexport class CustomToolRegistryError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"CustomToolRegistryError\";\n  }\n}\n\nconst customToolRegistry = new Map<string, RegisteredCustomTool>();\n\nfunction normalizeSegment(value: string, field: \"namespace\" | \"name\"): string {\n  const normalized = value.trim();\n  if (!normalized) {\n    throw new CustomToolRegistryError(`Custom tool ${field} is required.`);\n  }\n  if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(normalized)) {\n    throw new CustomToolRegistryError(\n      `Invalid custom tool ${field}: \"${value}\". Use letters, numbers, \"_\" or \"-\".`\n    );\n  }\n  return normalized;\n}\n\nfunction normalizeNamespace(namespace?: string): string {\n  const resolved = normalizeSegment(\n    namespace ?? DEFAULT_CUSTOM_NAMESPACE,\n    \"namespace\"\n  );\n  if (RESERVED_NAMESPACES.has(resolved.toLowerCase())) {\n    throw new CustomToolRegistryError(\n      `Namespace \"${resolved}\" is reserved for platform tools.`\n    );\n  }\n  return resolved;\n}\n\nfunction normalizeName(name: string): string {\n  if (name.includes(\".\")) {\n    throw new CustomToolRegistryError(\n      `Custom tool name \"${name}\" must not include \".\"; use namespace + name.`\n    );\n  }\n  return normalizeSegment(name, \"name\");\n}\n\nfunction buildFullName(namespace: string, shortName: string): string {\n  return `${namespace}.${shortName}`;\n}\n\nfunction unwrapSchema(schema: z.ZodTypeAny): {\n  schema: z.ZodTypeAny;\n  required: boolean;\n} {\n  if (schema instanceof z.ZodOptional) {\n    return { schema: schema.unwrap(), required: false };\n  }\n  if (schema instanceof z.ZodDefault) {\n    const removeDefault = (\n      schema as unknown as { removeDefault?: () => z.ZodTypeAny }\n    ).removeDefault;\n    if (typeof removeDefault === \"function\") {\n      return { schema: removeDefault.call(schema), required: false };\n    }\n    const inner = (schema as unknown as { _def?: { innerType?: z.ZodTypeAny } })\n      ._def?.innerType;\n    return { schema: inner ?? schema, required: false };\n  }\n  return { schema, required: true };\n}\n\nfunction resolveParameterType(schema: z.ZodTypeAny): {\n  type: McpParameterDef[\"type\"];\n  enum?: string[];\n} {\n  if (schema instanceof z.ZodString) {\n    return { type: \"string\" };\n  }\n  if (schema instanceof z.ZodEnum) {\n    return { type: \"string\", enum: schema.options };\n  }\n  if (schema instanceof z.ZodNativeEnum) {\n    const values = Object.values(schema.enum).filter(\n      (value): value is string => typeof value === \"string\"\n    );\n    return values.length > 0\n      ? { type: \"string\", enum: values }\n      : { type: \"string\" };\n  }\n  if (schema instanceof z.ZodLiteral) {\n    const literalValue = schema.value;\n    if (typeof literalValue === \"string\") {\n      return { type: \"string\", enum: [literalValue] };\n    }\n    if (typeof literalValue === \"number\") {\n      return { type: \"number\" };\n    }\n    if (typeof literalValue === \"boolean\") {\n      return { type: \"boolean\" };\n    }\n    return { type: \"object\" };\n  }\n  if (schema instanceof z.ZodNumber) {\n    return { type: \"number\" };\n  }\n  if (schema instanceof z.ZodBoolean) {\n    return { type: \"boolean\" };\n  }\n  if (schema instanceof z.ZodArray) {\n    return { type: \"array\" };\n  }\n  return { type: \"object\" };\n}\n\nfunction schemaTypeLabel(schema: z.ZodTypeAny): string {\n  if (schema instanceof z.ZodString || schema instanceof z.ZodEnum) {\n    return \"string\";\n  }\n  if (schema instanceof z.ZodNumber) {\n    return \"number\";\n  }\n  if (schema instanceof z.ZodBoolean) {\n    return \"boolean\";\n  }\n  if (schema instanceof z.ZodArray) {\n    return \"array\";\n  }\n  if (schema instanceof z.ZodObject) {\n    return \"object\";\n  }\n  return \"unknown\";\n}\n\nfunction parseObjectSchema<TInput extends AnyZodObject>(\n  value: TInput,\n  fieldName: string\n): TInput {\n  if (!(value instanceof z.ZodObject)) {\n    throw new CustomToolRegistryError(\n      `${fieldName} must be a Zod object schema.`\n    );\n  }\n  return value;\n}\n\nfunction deriveParameters(schema: AnyZodObject): {\n  parameters: Record<string, McpParameterDef>;\n  required: string[];\n} {\n  const shape = schema.shape;\n  const parameters: Record<string, McpParameterDef> = {};\n  const required: string[] = [];\n\n  for (const [key, raw] of Object.entries(shape)) {\n    const { schema: unwrapped, required: isRequired } = unwrapSchema(\n      raw as z.ZodTypeAny\n    );\n    const parameterType = resolveParameterType(unwrapped);\n    parameters[key] = {\n      type: parameterType.type,\n      description: (raw as z.ZodTypeAny).description ?? `${key} parameter`,\n      ...(parameterType.enum ? { enum: parameterType.enum } : {}),\n    };\n    if (isRequired) {\n      required.push(key);\n    }\n  }\n\n  return { parameters, required };\n}\n\nfunction deriveResponse(schema: z.ZodTypeAny): McpResponseDef {\n  if (schema instanceof z.ZodObject) {\n    const fields = Object.fromEntries(\n      Object.entries(schema.shape).map(([key, value]) => {\n        const zodValue = value as z.ZodTypeAny;\n        const label = schemaTypeLabel(unwrapSchema(zodValue).schema);\n        const description = zodValue.description ?? \"custom output field\";\n        return [key, `${label} — ${description}`];\n      })\n    );\n    return {\n      description: \"Custom tool result payload\",\n      fields,\n    };\n  }\n\n  return {\n    description: \"Custom tool result payload\",\n    fields: {\n      result: `${schemaTypeLabel(schema)} — custom output payload`,\n    },\n  };\n}\n\nfunction buildContract<\n  TInput extends AnyZodObject,\n  TOutput extends z.ZodTypeAny,\n>(\n  fullName: string,\n  namespace: string,\n  registration: CustomToolRegistration<TInput, TOutput>,\n  inputSchema: TInput\n): McpToolContract {\n  const { parameters, required } = deriveParameters(inputSchema);\n  return {\n    name: fullName,\n    description: registration.description,\n    parameters,\n    required,\n    response: deriveResponse(registration.outputSchema),\n    ownerModule: registration.ownerModule ?? `${namespace}-extension`,\n    ontologyPrimitive: registration.ontologyPrimitive ?? \"task\",\n    tier: registration.tier ?? \"workhorse\",\n  };\n}\n\n/**\n * Register a custom SDK tool in the in-memory registry.\n * @param registration - The tool definition including name, schemas, and handler.\n * @param options - Optional flags; set `replace` to overwrite an existing registration.\n * @returns The fully resolved registered tool entry.\n */\nexport function registerCustomTool<\n  TInput extends AnyZodObject,\n  TOutput extends z.ZodTypeAny,\n>(\n  registration: CustomToolRegistration<TInput, TOutput>,\n  options: { replace?: boolean } = {}\n): RegisteredCustomTool {\n  const namespace = normalizeNamespace(registration.namespace);\n  const shortName = normalizeName(registration.name);\n  const fullName = buildFullName(namespace, shortName);\n\n  if (customToolRegistry.has(fullName) && !options.replace) {\n    throw new CustomToolRegistryError(\n      `Custom tool \"${fullName}\" is already registered.`\n    );\n  }\n\n  const inputSchema = parseObjectSchema(\n    registration.inputSchema,\n    \"inputSchema\"\n  );\n  const outputSchema = registration.outputSchema;\n  const contract = buildContract(\n    fullName,\n    namespace,\n    registration,\n    inputSchema\n  );\n  const metadata: CustomToolMetadata = {\n    category: registration.metadata?.category,\n    tags: registration.metadata?.tags ?? [],\n    requiredScopes: registration.metadata?.requiredScopes ?? [\"custom:execute\"],\n  };\n\n  const registered: RegisteredCustomTool = {\n    fullName,\n    namespace,\n    shortName,\n    metadata,\n    contract,\n    inputSchema,\n    outputSchema,\n    invoke: async (input, context) => {\n      const parsedInput = inputSchema.parse(input);\n      const rawOutput = await registration.handler(parsedInput, context);\n      return outputSchema.parse(rawOutput);\n    },\n  };\n\n  customToolRegistry.set(fullName, registered);\n  return registered;\n}\n\n/**\n * Remove a custom SDK tool from the registry.\n * @param fullName - Fully qualified tool name (`namespace.name`).\n * @returns `true` if the tool was found and removed, `false` otherwise.\n */\nexport function unregisterCustomTool(fullName: string): boolean {\n  return customToolRegistry.delete(fullName.trim());\n}\n\n/**\n * Get a custom SDK tool by fully qualified name.\n * @param fullName - Fully qualified tool name (`namespace.name`).\n * @returns The registered tool entry, or `undefined` if not found.\n */\nexport function getRegisteredCustomTool(\n  fullName: string\n): RegisteredCustomTool | undefined {\n  return customToolRegistry.get(fullName.trim());\n}\n\n/**\n * List all registered custom SDK tools, sorted alphabetically by full name.\n * @returns An array of all registered tool entries.\n */\nexport function listRegisteredCustomTools(): RegisteredCustomTool[] {\n  return [...customToolRegistry.values()].sort((left, right) =>\n    left.fullName.localeCompare(right.fullName)\n  );\n}\n\n/**\n * Clear the registered custom tool registry.\n */\nexport function clearRegisteredCustomTools(): void {\n  customToolRegistry.clear();\n}\n\n/**\n * Invoke a registered custom SDK tool by fully qualified name.\n * @param fullName - Fully qualified tool name (`namespace.name`).\n * @param params - JSON-serializable input parameters for the tool handler.\n * @param context - Invocation context indicating the call source.\n * @returns The validated output from the tool handler.\n */\nexport async function invokeRegisteredCustomTool(\n  fullName: string,\n  params: JsonObject,\n  context: CustomToolInvocationContext\n): Promise<unknown> {\n  const registered = getRegisteredCustomTool(fullName);\n  if (!registered) {\n    throw new CustomToolRegistryError(\n      `Custom tool \"${fullName}\" is not registered.`\n    );\n  }\n  return registered.invoke(params, context);\n}\n"]}

package/dist/decisionsClient.d.ts

@@ -0,0 +1,111 @@
+import { TopicIdentifierInput, ListJudgmentsResponse, GetJudgmentResponse, JudgmentReadinessResponse, JudgmentCalibrationResponse, ListResult, PendingJudgmentOutcomeRecord, JudgmentTransitionAuditIntegrityResponse, RecordJudgmentResponse, RecordJudgmentOutcomeResponse } from './types.js';
+export { PendingJudgmentOutcomeReviewResponse } from './types.js';
+import { GatewayClientConfig, PlatformGatewaySuccess } from './coreClient.js';
+export { LucernApiError } from './coreClient.js';
+import './contracts/workflow-runtime.contract.js';
+import './contracts/lens-workflow.contract.js';
+import './contracts/lens-filter.contract.js';
+
+/** Configuration for the decisions client. */
+type DecisionsClientConfig = GatewayClientConfig;
+/** Input for recording a new judgment (irreversible decision commitment). */
+type RecordJudgmentInput = {
+    title: string;
+    summary?: string;
+    rationale: string;
+    topicId?: string;
+    confidence?: number;
+    decisionConfidence?: number;
+    judgmentType?: string;
+    decisionType?: string;
+    beliefIds?: string[];
+    keyUncertainties?: string[];
+    alternativesConsidered?: string[];
+    decisionMakers?: string[];
+    companyId?: string;
+    amount?: number;
+    valuation?: number;
+    terms?: string;
+    themeIds?: string[];
+} & TopicIdentifierInput;
+/** Filter parameters for listing judgments within a topic scope. */
+type ListJudgmentsInput = {
+    topicId?: string;
+    includeArchived?: boolean;
+    limit?: number;
+} & TopicIdentifierInput;
+/** Input for recording the real-world outcome of a judgment. */
+type RecordJudgmentOutcomeInput = {
+    outcome: "pending" | "successful" | "unsuccessful" | "mixed" | "unknown" | "too_early";
+    outcomeNotes?: string;
+    notes?: string;
+};
+/** Input for retrieving judgment calibration analytics. */
+type GetJudgmentCalibrationInput = {
+    topicId?: string;
+} & TopicIdentifierInput;
+/** Input for listing judgments still awaiting outcome review. */
+type ListPendingJudgmentOutcomeReviewInput = {
+    topicId?: string;
+} & TopicIdentifierInput;
+/** Input for checking audit integrity of judgment state transitions. */
+type GetJudgmentTransitionAuditIntegrityInput = {
+    topicId?: string;
+    judgmentId?: string;
+    includePassing?: boolean;
+} & TopicIdentifierInput;
+/**
+ * Create the judgments client for decision lifecycle operations.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to manage judgments, outcomes, readiness, and calibration.
+ */
+declare function createDecisionsClient(config?: DecisionsClientConfig): {
+    /**
+     * List judgments for a topic scope.
+     */
+    listJudgments(query: ListJudgmentsInput): Promise<PlatformGatewaySuccess<ListJudgmentsResponse>>;
+    /**
+     * Get a single judgment by identifier.
+     */
+    getJudgment(judgmentId: string): Promise<PlatformGatewaySuccess<GetJudgmentResponse>>;
+    /**
+     * Get readiness signals for creating a judgment.
+     */
+    getJudgmentReadiness(query: {
+        topicId?: string;
+    } & TopicIdentifierInput): Promise<PlatformGatewaySuccess<JudgmentReadinessResponse>>;
+    /**
+     * Get calibration analytics for judgment outcomes.
+     */
+    getJudgmentCalibration(query: GetJudgmentCalibrationInput): Promise<PlatformGatewaySuccess<JudgmentCalibrationResponse>>;
+    /**
+     * List judgments still awaiting outcome review.
+     */
+    listPendingOutcomeReviews(query: ListPendingJudgmentOutcomeReviewInput): Promise<PlatformGatewaySuccess<ListResult<PendingJudgmentOutcomeRecord, "reviews">>>;
+    /**
+     * @deprecated Use listPendingOutcomeReviews.
+     */
+    listPendingJudgmentOutcomeReview(query: ListPendingJudgmentOutcomeReviewInput): Promise<PlatformGatewaySuccess<ListResult<PendingJudgmentOutcomeRecord, "reviews">>>;
+    /**
+     * Get audit integrity checks for judgment transitions.
+     */
+    getJudgmentTransitionAuditIntegrity(query: GetJudgmentTransitionAuditIntegrityInput): Promise<PlatformGatewaySuccess<JudgmentTransitionAuditIntegrityResponse>>;
+    /**
+     * Create a judgment.
+     */
+    createJudgment(input: RecordJudgmentInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<RecordJudgmentResponse>>;
+    /**
+     * @deprecated Use createJudgment.
+     */
+    recordJudgment(input: RecordJudgmentInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<RecordJudgmentResponse>>;
+    /**
+     * Update the outcome for an existing judgment.
+     */
+    updateJudgmentOutcome(judgmentId: string, input: RecordJudgmentOutcomeInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<RecordJudgmentOutcomeResponse>>;
+    /**
+     * @deprecated Use updateJudgmentOutcome.
+     */
+    recordJudgmentOutcome(judgmentId: string, input: RecordJudgmentOutcomeInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<RecordJudgmentOutcomeResponse>>;
+};
+
+export { type DecisionsClientConfig, type GetJudgmentCalibrationInput, GetJudgmentResponse, type GetJudgmentTransitionAuditIntegrityInput, JudgmentCalibrationResponse, JudgmentReadinessResponse, JudgmentTransitionAuditIntegrityResponse, type ListJudgmentsInput, ListJudgmentsResponse, type ListPendingJudgmentOutcomeReviewInput, PlatformGatewaySuccess, type RecordJudgmentInput, type RecordJudgmentOutcomeInput, RecordJudgmentOutcomeResponse, RecordJudgmentResponse, createDecisionsClient };