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

package/dist/manifests/tenant-client-manifest.d.ts

@@ -0,0 +1,322 @@
+import { TENANT_CLIENT_CONTRACT_VERSION, TENANT_CLIENT_AUTH_MODES, TENANT_CLIENT_PRINCIPAL_TYPES, TENANT_CLIENT_REQUIRED_CONTEXT_FIELDS, TENANT_CLIENT_OPTIONAL_CONTEXT_FIELDS, TENANT_CLIENT_INSTALL_TOKEN_ENV, TENANT_CLIENT_INSTALL_TOKEN_INFISICAL_PATH, TENANT_CLIENT_FORBIDDEN_INSTALL_TOKEN_INFISICAL_PATHS, TENANT_CLIENT_FORBIDDEN_SECRET_ENV, TENANT_CLIENT_INSTALLABLE_PACKAGES, TENANT_CLIENT_INSTALL_PROFILES, TENANT_CLIENT_PUBLIC_IMPORTS, TENANT_CLIENT_COMPONENT_CONFIG_IMPORTS, TENANT_CLIENT_REQUIRED_SDK_NAMESPACES, TENANT_CLIENT_CAPABILITIES, TENANT_CLIENT_ISOLATION_RULES, TENANT_CLIENT_FORBIDDEN_IMPORT_PATTERNS } from '../tenant-client.contract.js';
+
+type TenantClientManifest = {
+    readonly manifestVersion: "1.0.0";
+    readonly contractVersion: typeof TENANT_CLIENT_CONTRACT_VERSION;
+    readonly auth: {
+        readonly modes: typeof TENANT_CLIENT_AUTH_MODES;
+        readonly principalTypes: typeof TENANT_CLIENT_PRINCIPAL_TYPES;
+        readonly requiredContextFields: typeof TENANT_CLIENT_REQUIRED_CONTEXT_FIELDS;
+        readonly optionalContextFields: typeof TENANT_CLIENT_OPTIONAL_CONTEXT_FIELDS;
+    };
+    readonly installToken: {
+        readonly env: typeof TENANT_CLIENT_INSTALL_TOKEN_ENV;
+        readonly infisicalPath: typeof TENANT_CLIENT_INSTALL_TOKEN_INFISICAL_PATH;
+        readonly forbiddenInfisicalPaths: typeof TENANT_CLIENT_FORBIDDEN_INSTALL_TOKEN_INFISICAL_PATHS;
+        readonly forbiddenSecretEnv: typeof TENANT_CLIENT_FORBIDDEN_SECRET_ENV;
+    };
+    readonly packages: {
+        readonly installable: typeof TENANT_CLIENT_INSTALLABLE_PACKAGES;
+        readonly installProfiles: typeof TENANT_CLIENT_INSTALL_PROFILES;
+        readonly directImports: typeof TENANT_CLIENT_PUBLIC_IMPORTS;
+        readonly componentConfigImports: typeof TENANT_CLIENT_COMPONENT_CONFIG_IMPORTS;
+    };
+    readonly sdk: {
+        readonly requiredNamespaces: typeof TENANT_CLIENT_REQUIRED_SDK_NAMESPACES;
+    };
+    readonly capabilities: typeof TENANT_CLIENT_CAPABILITIES;
+    readonly isolationRules: typeof TENANT_CLIENT_ISOLATION_RULES;
+    readonly forbiddenImportPatterns: typeof TENANT_CLIENT_FORBIDDEN_IMPORT_PATTERNS;
+};
+declare const TENANT_CLIENT_MANIFEST: {
+    readonly manifestVersion: "1.0.0";
+    readonly contractVersion: "2026-04-27";
+    readonly auth: {
+        readonly modes: readonly ["interactive_user", "service_principal", "tenant_api_key", "session_token"];
+        readonly principalTypes: readonly ["human", "service", "agent"];
+        readonly requiredContextFields: readonly ["tenantId", "workspaceId", "principalId", "authMode", "scopes"];
+        readonly optionalContextFields: readonly ["principalType", "roles", "sessionId", "delegationChain"];
+    };
+    readonly installToken: {
+        readonly env: "INSTALL_LUCERN_NPM";
+        readonly infisicalPath: "tenants/shared";
+        readonly forbiddenInfisicalPaths: readonly ["/platform/publish"];
+        readonly forbiddenSecretEnv: readonly ["NPM_TOKEN"];
+    };
+    readonly packages: {
+        readonly installable: 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;
+        }];
+        readonly installProfiles: 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";
+        }];
+        readonly directImports: 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.";
+        }];
+        readonly componentConfigImports: 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.";
+        }];
+    };
+    readonly sdk: {
+        readonly requiredNamespaces: 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"];
+    };
+    readonly 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"];
+    }];
+    readonly isolationRules: 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.";
+    }];
+    readonly forbiddenImportPatterns: 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.";
+    }];
+};
+
+export { TENANT_CLIENT_MANIFEST, type TenantClientManifest };