@lucern/contracts 0.3.0-alpha.1 → 0.3.0-alpha.11

package/dist/tenant-client.contract.d.ts

@@ -0,0 +1,349 @@
+/**
+ * Tenant client contract
+ *
+ * Defines the generic boundary for any customer-owned product that consumes
+ * Lucern through the SDK, hosted API, or MCP server. Tenant clients may run
+ * their own UI, auth provider, deployment, and data plane, but reasoning
+ * operations must enter through the published packages below.
+ */
+declare const TENANT_CLIENT_CONTRACT_VERSION: "2026-04-27";
+declare const TENANT_CLIENT_AUTH_MODES: readonly ["interactive_user", "service_principal", "tenant_api_key", "session_token"];
+type TenantClientAuthMode = (typeof TENANT_CLIENT_AUTH_MODES)[number];
+declare const TENANT_CLIENT_PRINCIPAL_TYPES: readonly ["human", "service", "agent"];
+type TenantClientPrincipalType = (typeof TENANT_CLIENT_PRINCIPAL_TYPES)[number];
+declare const TENANT_CLIENT_REQUIRED_CONTEXT_FIELDS: readonly ["tenantId", "workspaceId", "principalId", "authMode", "scopes"];
+type TenantClientRequiredContextField = (typeof TENANT_CLIENT_REQUIRED_CONTEXT_FIELDS)[number];
+declare const TENANT_CLIENT_OPTIONAL_CONTEXT_FIELDS: readonly ["principalType", "roles", "sessionId", "delegationChain"];
+type TenantClientOptionalContextField = (typeof TENANT_CLIENT_OPTIONAL_CONTEXT_FIELDS)[number];
+declare const TENANT_CLIENT_INSTALL_TOKEN_ENV: "INSTALL_LUCERN_NPM";
+declare const TENANT_CLIENT_INSTALL_TOKEN_INFISICAL_PATH: "tenants/shared";
+declare const TENANT_CLIENT_FORBIDDEN_INSTALL_TOKEN_INFISICAL_PATHS: readonly ["/platform/publish"];
+declare const TENANT_CLIENT_FORBIDDEN_SECRET_ENV: readonly ["NPM_TOKEN"];
+type TenantClientForbiddenInstallTokenInfisicalPath = (typeof TENANT_CLIENT_FORBIDDEN_INSTALL_TOKEN_INFISICAL_PATHS)[number];
+type TenantClientForbiddenSecretEnv = (typeof TENANT_CLIENT_FORBIDDEN_SECRET_ENV)[number];
+declare const TENANT_CLIENT_INSTALLABLE_PACKAGES: readonly [{
+    readonly packageName: "@lucern/access-control";
+    readonly role: "runtime_entrypoint";
+    readonly directTenantImport: true;
+}, {
+    readonly packageName: "@lucern/agent";
+    readonly role: "platform_runtime";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/auth";
+    readonly role: "sdk_dependency";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/cli";
+    readonly role: "developer_tool";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/client-core";
+    readonly role: "sdk_dependency";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/confidence";
+    readonly role: "sdk_dependency";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/config";
+    readonly role: "configuration";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/contracts";
+    readonly role: "contract_entrypoint";
+    readonly directTenantImport: true;
+}, {
+    readonly packageName: "@lucern/control-plane";
+    readonly role: "component_runtime";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/developer-kit";
+    readonly role: "developer_tool";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/events";
+    readonly role: "sdk_dependency";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/graph-primitives";
+    readonly role: "sdk_dependency";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/graph-sync";
+    readonly role: "host_addon_runtime";
+    readonly directTenantImport: true;
+}, {
+    readonly packageName: "@lucern/mcp";
+    readonly role: "runtime_entrypoint";
+    readonly directTenantImport: true;
+}, {
+    readonly packageName: "@lucern/pack-host";
+    readonly role: "platform_runtime";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/pack-installer";
+    readonly role: "developer_tool";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/proof-compiler";
+    readonly role: "developer_tool";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/react";
+    readonly role: "runtime_entrypoint";
+    readonly directTenantImport: true;
+}, {
+    readonly packageName: "@lucern/reasoning-kernel";
+    readonly role: "component_runtime";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/sdk";
+    readonly role: "runtime_entrypoint";
+    readonly directTenantImport: true;
+}, {
+    readonly packageName: "@lucern/secrets";
+    readonly role: "sdk_dependency";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/server-core";
+    readonly role: "platform_runtime";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/testing";
+    readonly role: "test_support";
+    readonly directTenantImport: false;
+}, {
+    readonly packageName: "@lucern/types";
+    readonly role: "contract_entrypoint";
+    readonly directTenantImport: true;
+}];
+type TenantClientInstallablePackage = (typeof TENANT_CLIENT_INSTALLABLE_PACKAGES)[number];
+type TenantClientPackageRole = TenantClientInstallablePackage["role"];
+type TenantClientInstallablePackageName = TenantClientInstallablePackage["packageName"];
+/**
+ * Direct package installs are package.json entries owned by the tenant repo.
+ * Direct imports are source-code imports that tenant application code may use.
+ *
+ * These concepts intentionally differ: `@lucern/cli` is a direct install when a
+ * tenant repo needs the `lucern` binary, but it is not a direct application
+ * import. `@lucern/reasoning-kernel` and `@lucern/control-plane` are direct installs
+ * for Convex component binding, while tenant app code should only import their
+ * explicit component config subpaths.
+ */
+type TenantClientInstallProfile = {
+    id: string;
+    description: string;
+    packageNames: readonly TenantClientInstallablePackageName[];
+    dependencyField: "dependencies" | "devDependencies" | "mixed";
+};
+declare const TENANT_CLIENT_FULL_SUITE_PACKAGE_NAMES: readonly TenantClientInstallablePackageName[];
+declare const TENANT_CLIENT_INSTALL_PROFILES: readonly [{
+    readonly id: "core_app_runtime";
+    readonly description: "Smallest tenant app/runtime install for typed Lucern API calls plus tool-access policy helpers.";
+    readonly packageNames: readonly ["@lucern/sdk", "@lucern/access-control"];
+    readonly dependencyField: "dependencies";
+}, {
+    readonly id: "react_app_runtime";
+    readonly description: "React tenant app install for hooks, provider, curated graph components, and direct SDK calls.";
+    readonly packageNames: readonly ["@lucern/react", "@lucern/sdk", "@lucern/access-control"];
+    readonly dependencyField: "dependencies";
+}, {
+    readonly id: "convex_components";
+    readonly description: "Tenant Convex host install for binding the Lucern control-plane and reasoning-kernel components.";
+    readonly packageNames: readonly ["@lucern/control-plane", "@lucern/reasoning-kernel"];
+    readonly dependencyField: "dependencies";
+}, {
+    readonly id: "graph_mirroring_addon";
+    readonly description: "Optional tenant Convex host install for Neo4j graph projection, edge topology writes, backfill, health checks, and query proxy helpers.";
+    readonly packageNames: readonly ["@lucern/graph-sync"];
+    readonly dependencyField: "dependencies";
+}, {
+    readonly id: "operator_cli";
+    readonly description: "Developer/operator install for the `lucern` binary, including tenant bootstrap seed commands.";
+    readonly packageNames: readonly ["@lucern/cli"];
+    readonly dependencyField: "devDependencies";
+}, {
+    readonly id: "mcp_runtime";
+    readonly description: "Agent runtime install for the standalone Lucern MCP server and hosted route helpers.";
+    readonly packageNames: readonly ["@lucern/mcp"];
+    readonly dependencyField: "dependencies";
+}, {
+    readonly id: "contracts_and_types";
+    readonly description: "Compile-time contract/type install for codegen, audits, and tenant integration validation.";
+    readonly packageNames: readonly ["@lucern/contracts", "@lucern/types"];
+    readonly dependencyField: "dependencies";
+}, {
+    readonly id: "full_suite";
+    readonly description: "Full coherent Lucern package suite for design-partner repos that want every published runtime, tool, component, test, and config package pinned together.";
+    readonly packageNames: readonly ("@lucern/access-control" | "@lucern/agent" | "@lucern/auth" | "@lucern/cli" | "@lucern/client-core" | "@lucern/confidence" | "@lucern/config" | "@lucern/contracts" | "@lucern/control-plane" | "@lucern/developer-kit" | "@lucern/events" | "@lucern/graph-primitives" | "@lucern/graph-sync" | "@lucern/mcp" | "@lucern/pack-host" | "@lucern/pack-installer" | "@lucern/proof-compiler" | "@lucern/react" | "@lucern/reasoning-kernel" | "@lucern/sdk" | "@lucern/secrets" | "@lucern/server-core" | "@lucern/testing" | "@lucern/types")[];
+    readonly dependencyField: "mixed";
+}];
+type TenantClientInstallProfileId = (typeof TENANT_CLIENT_INSTALL_PROFILES)[number]["id"];
+/**
+ * Direct imports tenant-owned product code may use. This is intentionally
+ * smaller than TENANT_CLIENT_INSTALLABLE_PACKAGES: several publishable packages
+ * are installed as SDK dependencies, tooling, or platform runtimes but should
+ * not become the application integration surface.
+ */
+declare const TENANT_CLIENT_PUBLIC_IMPORTS: readonly [{
+    readonly packageName: "@lucern/sdk";
+    readonly surface: "runtime";
+    readonly subpaths: "published_exports";
+    readonly description: "TypeScript SDK runtime and generated operation namespaces.";
+}, {
+    readonly packageName: "@lucern/react";
+    readonly surface: "runtime";
+    readonly subpaths: "published_exports";
+    readonly description: "React bindings for tenant-owned UI applications.";
+}, {
+    readonly packageName: "@lucern/mcp";
+    readonly surface: "runtime";
+    readonly subpaths: "published_exports";
+    readonly description: "MCP client/server entry points and hosted route helpers.";
+}, {
+    readonly packageName: "@lucern/graph-sync";
+    readonly surface: "runtime";
+    readonly subpaths: "published_exports";
+    readonly description: "Optional Neo4j graph mirroring host actions, edge API, query proxy, backfill, and health helpers.";
+}, {
+    readonly packageName: "@lucern/contracts";
+    readonly surface: "contract";
+    readonly subpaths: "published_exports";
+    readonly description: "Published type and manifest contracts.";
+}, {
+    readonly packageName: "@lucern/access-control";
+    readonly surface: "runtime";
+    readonly subpaths: "published_exports";
+    readonly description: "Tenant runtime access-control helpers, including effective tool access.";
+}, {
+    readonly packageName: "@lucern/types";
+    readonly surface: "contract";
+    readonly subpaths: "published_exports";
+    readonly description: "Published type-only helpers for tenant integration code.";
+}];
+type TenantClientPublicImport = (typeof TENANT_CLIENT_PUBLIC_IMPORTS)[number];
+type TenantClientPublicPackage = TenantClientPublicImport["packageName"];
+type TenantClientPublicSurface = TenantClientPublicImport["surface"];
+declare const TENANT_CLIENT_COMPONENT_CONFIG_IMPORTS: readonly [{
+    readonly packageName: "@lucern/control-plane";
+    readonly importPath: "@lucern/control-plane/convex.config";
+    readonly surface: "component_config";
+    readonly description: "Convex component binding config for tenant deployments that install the Lucern control plane.";
+}, {
+    readonly packageName: "@lucern/reasoning-kernel";
+    readonly importPath: "@lucern/reasoning-kernel/convex.config";
+    readonly surface: "component_config";
+    readonly description: "Convex component binding config for tenant deployments that install the Lucern reasoning kernel.";
+}, {
+    readonly packageName: "@lucern/reasoning-kernel";
+    readonly importPath: "@lucern/reasoning-kernel/runtime.config";
+    readonly surface: "component_config";
+    readonly description: "Runtime config alias for tenant deployments that install the Lucern reasoning kernel.";
+}];
+type TenantClientComponentConfigImport = (typeof TENANT_CLIENT_COMPONENT_CONFIG_IMPORTS)[number];
+type TenantClientAllowedImport = TenantClientPublicImport | TenantClientComponentConfigImport;
+declare function findTenantClientInstallablePackage(packageName: string): TenantClientInstallablePackage | undefined;
+declare function isTenantClientInstallablePackage(packageName: string): boolean;
+declare const TENANT_CLIENT_REQUIRED_SDK_NAMESPACES: readonly ["bootstrap", "context", "beliefs", "evidence", "questions", "graph", "worktrees", "topics", "edges", "contradictions", "contracts", "graphIntel", "graphIntelligence", "graphAnalysis", "graphRecommendations", "orgGraphSearch", "embeddings", "ontologyLinks", "graphStateClassifier", "tools", "identity", "modelRuntime", "events", "jobs", "telemetry"];
+type TenantClientRequiredSdkNamespace = (typeof TENANT_CLIENT_REQUIRED_SDK_NAMESPACES)[number];
+declare const TENANT_CLIENT_CAPABILITIES: readonly [{
+    readonly id: "identity.bootstrap_session";
+    readonly description: "Start a scoped Lucern session for a tenant principal.";
+    readonly surfaces: readonly ["@lucern/sdk", "@lucern/mcp"];
+    readonly requiredContextFields: readonly ["tenantId", "workspaceId", "principalId", "authMode", "scopes"];
+}, {
+    readonly id: "reasoning.context.compile";
+    readonly description: "Compile tenant and workspace scoped reasoning context.";
+    readonly surfaces: readonly ["@lucern/sdk", "@lucern/react", "@lucern/mcp"];
+    readonly requiredContextFields: readonly ["tenantId", "workspaceId", "principalId", "authMode", "scopes"];
+}, {
+    readonly id: "reasoning.graph.read";
+    readonly description: "Read beliefs, evidence, questions, topics, graph edges, and lineage.";
+    readonly surfaces: readonly ["@lucern/sdk", "@lucern/react", "@lucern/mcp"];
+    readonly requiredContextFields: readonly ["tenantId", "workspaceId", "principalId", "authMode", "scopes"];
+}, {
+    readonly id: "reasoning.graph.write";
+    readonly description: "Create and update graph objects through authorized APIs.";
+    readonly surfaces: readonly ["@lucern/sdk", "@lucern/mcp"];
+    readonly requiredContextFields: readonly ["tenantId", "workspaceId", "principalId", "authMode", "scopes"];
+}, {
+    readonly id: "reasoning.graph_intelligence.run";
+    readonly description: "Discover and run Graph Intelligence query recipes for structural graph analysis.";
+    readonly surfaces: readonly ["@lucern/sdk", "@lucern/cli", "@lucern/mcp"];
+    readonly requiredContextFields: readonly ["tenantId", "workspaceId", "principalId", "authMode", "scopes"];
+}, {
+    readonly id: "reasoning.graph_mirroring.install";
+    readonly description: "Install and run the optional Neo4j graph mirror for paid or enterprise tenant deployments.";
+    readonly surfaces: readonly ["@lucern/graph-sync", "@lucern/cli"];
+    readonly requiredContextFields: readonly ["tenantId", "workspaceId", "principalId", "authMode", "scopes"];
+}, {
+    readonly id: "workflow.worktree_lifecycle";
+    readonly description: "Create, review, merge, and close scoped worktrees.";
+    readonly surfaces: readonly ["@lucern/sdk", "@lucern/react", "@lucern/mcp"];
+    readonly requiredContextFields: readonly ["tenantId", "workspaceId", "principalId", "authMode", "scopes"];
+}];
+type TenantClientCapability = (typeof TENANT_CLIENT_CAPABILITIES)[number];
+type TenantClientCapabilityId = TenantClientCapability["id"];
+declare const TENANT_CLIENT_ISOLATION_RULES: readonly [{
+    readonly id: "tenant_workspace_scope_required";
+    readonly description: "Runtime operations must resolve both tenantId and workspaceId before reaching Lucern reasoning state.";
+}, {
+    readonly id: "principal_audit_required";
+    readonly description: "Runtime operations must carry principalId, authMode, and scopes for audit attribution.";
+}, {
+    readonly id: "no_private_lucern_imports";
+    readonly description: "Tenant code must not import Lucern source, Convex internals, generated adapters, or unpublished package internals.";
+}];
+type TenantClientIsolationRule = (typeof TENANT_CLIENT_ISOLATION_RULES)[number];
+declare const TENANT_CLIENT_FORBIDDEN_IMPORT_PATTERNS: readonly [{
+    readonly id: "deep_src_import";
+    readonly pattern: "^@lucern/[^/]+/src(?:/|$)";
+    readonly description: "Published packages must not be bypassed through src paths.";
+}, {
+    readonly id: "deep_dist_import";
+    readonly pattern: "^@lucern/[^/]+/dist(?:/|$)";
+    readonly description: "Published package exports must be used instead of dist file paths.";
+}, {
+    readonly id: "generated_adapter_import";
+    readonly pattern: "^@lucern/[^/]+/(?:adapters/)?_generated(?:/|$)";
+    readonly description: "Generated Lucern adapters are internal deployment artifacts.";
+}, {
+    readonly id: "private_runtime_import";
+    readonly pattern: "^@lucern/[^/]+/(?:internal|private)(?:/|$)";
+    readonly description: "Internal and private package subpaths are not public SDK API.";
+}, {
+    readonly id: "workspace_source_import";
+    readonly pattern: "^(?:packages|modules|services|lucern|apps)/(?:.+/)?src(?:/|$)";
+    readonly description: "Tenant clients must not import source files from the Lucern monorepo.";
+}, {
+    readonly id: "root_alias_lucern_import";
+    readonly pattern: "^@/(?:lucern|packages|modules|services|apps)(?:/|$)";
+    readonly description: "Tenant clients must not depend on Lucern repo-local path aliases.";
+}, {
+    readonly id: "relative_lucern_source_import";
+    readonly pattern: "^\\.\\.?/(?:.+/)?(?:packages|modules|services|lucern|apps)(?:/|$)";
+    readonly description: "Tenant clients must not reach back into Lucern source through relative paths.";
+}, {
+    readonly id: "monorepo_path_import";
+    readonly pattern: "lucern-repo";
+    readonly description: "Absolute imports that name the Lucern repository are not portable tenant code.";
+}];
+type TenantClientForbiddenImportPattern = (typeof TENANT_CLIENT_FORBIDDEN_IMPORT_PATTERNS)[number];
+type TenantClientForbiddenImportPatternId = TenantClientForbiddenImportPattern["id"];
+type TenantClientImportDecision = "public" | "forbidden" | "local" | "external";
+type TenantClientImportClassification = {
+    importPath: string;
+    decision: TenantClientImportDecision;
+    publicImport?: TenantClientAllowedImport;
+    pattern?: TenantClientForbiddenImportPattern;
+    reason: string;
+};
+declare function classifyTenantClientImport(importPath: string): TenantClientImportClassification;
+declare function isTenantClientPublicImport(importPath: string): boolean;
+declare function isTenantClientComponentConfigImport(importPath: string): boolean;
+declare function isTenantClientAllowedImport(importPath: string): boolean;
+declare function assertTenantClientImportAllowed(importPath: string): void;
+declare function formatTenantClientImportViolation(classification: TenantClientImportClassification): string;
+
+export { TENANT_CLIENT_AUTH_MODES, TENANT_CLIENT_CAPABILITIES, TENANT_CLIENT_COMPONENT_CONFIG_IMPORTS, TENANT_CLIENT_CONTRACT_VERSION, TENANT_CLIENT_FORBIDDEN_IMPORT_PATTERNS, TENANT_CLIENT_FORBIDDEN_INSTALL_TOKEN_INFISICAL_PATHS, TENANT_CLIENT_FORBIDDEN_SECRET_ENV, TENANT_CLIENT_FULL_SUITE_PACKAGE_NAMES, TENANT_CLIENT_INSTALLABLE_PACKAGES, TENANT_CLIENT_INSTALL_PROFILES, TENANT_CLIENT_INSTALL_TOKEN_ENV, TENANT_CLIENT_INSTALL_TOKEN_INFISICAL_PATH, TENANT_CLIENT_ISOLATION_RULES, TENANT_CLIENT_OPTIONAL_CONTEXT_FIELDS, TENANT_CLIENT_PRINCIPAL_TYPES, TENANT_CLIENT_PUBLIC_IMPORTS, TENANT_CLIENT_REQUIRED_CONTEXT_FIELDS, TENANT_CLIENT_REQUIRED_SDK_NAMESPACES, type TenantClientAllowedImport, type TenantClientAuthMode, type TenantClientCapability, type TenantClientCapabilityId, type TenantClientComponentConfigImport, type TenantClientForbiddenImportPattern, type TenantClientForbiddenImportPatternId, type TenantClientForbiddenInstallTokenInfisicalPath, type TenantClientForbiddenSecretEnv, type TenantClientImportClassification, type TenantClientImportDecision, type TenantClientInstallProfile, type TenantClientInstallProfileId, type TenantClientInstallablePackage, type TenantClientInstallablePackageName, type TenantClientIsolationRule, type TenantClientOptionalContextField, type TenantClientPackageRole, type TenantClientPrincipalType, type TenantClientPublicImport, type TenantClientPublicPackage, type TenantClientPublicSurface, type TenantClientRequiredContextField, type TenantClientRequiredSdkNamespace, assertTenantClientImportAllowed, classifyTenantClientImport, findTenantClientInstallablePackage, formatTenantClientImportViolation, isTenantClientAllowedImport, isTenantClientComponentConfigImport, isTenantClientInstallablePackage, isTenantClientPublicImport };