Eve library

Kuanyin Developer Guide

Guide

Revision 1

On this page

Comprehensive development guide for the Kuanyin (Ethics/Harm Prevention) domain libraries.

This guide covers local development setup, building, testing, debugging, and common development tasks for all 10 Kuanyin libraries.


Prerequisites#

Required Software#

Tool Version Purpose
Node.js >= 20.0 JavaScript runtime
pnpm >= 10.0 Package manager
Nx (via pnpm) Monorepo task runner
PostgreSQL 15+ Required for kuanyin-database development

Installation#

bash
# From the repository root
pnpm install

Database Setup (for kuanyin-database development)#

The kuanyin-database library defines schemas, migrations, and repositories that require a running PostgreSQL instance:

bash
# Start the development PostgreSQL instance
docker compose -f docker/docker-compose.dev.yml up -d

# Connection: postgresql://oshun:oshun_dev@localhost:5432/oshun_dev

For all other Kuanyin libraries (foundation, precognition, mindful-friction, etc.), no database or external services are required.


Project Structure#

All Kuanyin libraries live under libs/kuanyin/:

text
libs/kuanyin/
  foundation/          kuanyin-foundation          Core types and utilities
  database/            kuanyin-database            Schemas, migrations, repositories
  precognition/        kuanyin-precognition        Predictive harm detection (6 modules)
  community-harmony/   kuanyin-community-harmony   Community health (5 modules)
  mindful-friction/    kuanyin-mindful-friction     Intentional friction patterns (6 modules)
  performer-protection/ kuanyin-performer-protection Creator safety (6 modules)
  rehabilitation/      kuanyin-rehabilitation       Rehabilitation pathways (6 modules)
  merit-karma/         kuanyin-merit-karma          Merit and karma systems (5 modules)
  dharma-analytics/    kuanyin-dharma-analytics     Community metrics (5 modules)
  cross-domain/        kuanyin-cross-domain         Cross-domain ethics integration (5 modules)

Important: Kuanyin uses Nx project names without the @ scope prefix (e.g., kuanyin-foundation not @kuanyin/foundation). However, the npm package names in package.json use the @kuanyin/ scope. When running Nx commands, use the project name from project.json.

Library Dependency Graph#

text
kuanyin-foundation (types, constants, utilities, errors)
  |
  +-- kuanyin-database (schemas, migrations, repos, seeds)
  |     |
  |     +-- kuanyin-precognition        (predictive harm detection)
  |     +-- kuanyin-community-harmony   (community health)
  |     +-- kuanyin-mindful-friction    (intentional friction)
  |     +-- kuanyin-performer-protection (creator safety)
  |     +-- kuanyin-rehabilitation      (rehabilitation pathways)
  |     |
  |     +-- kuanyin-merit-karma         (merit and karma)
  |     +-- kuanyin-dharma-analytics    (analytics)
  |           |
  |           +-- kuanyin-cross-domain  (platform-wide integration)

Per-Library File Layout#

text
libs/kuanyin/{library}/
  src/
    index.ts               Public API barrel export
    {module}.ts            Module implementation
    {module}.spec.ts       Module tests
  package.json
  project.json
  tsconfig.json
  tsconfig.lib.json
  tsconfig.spec.json
  vitest.config.ts

Building Libraries#

Build a Single Library#

bash
pnpm nx build kuanyin-foundation
pnpm nx build kuanyin-database
pnpm nx build kuanyin-precognition
pnpm nx build kuanyin-mindful-friction
pnpm nx build kuanyin-performer-protection
pnpm nx build kuanyin-rehabilitation
pnpm nx build kuanyin-merit-karma
pnpm nx build kuanyin-dharma-analytics
pnpm nx build kuanyin-cross-domain
pnpm nx build kuanyin-community-harmony

Build All Kuanyin Libraries#

bash
pnpm nx run-many --target=build --projects=tag:scope:kuanyin

Build Configuration#

Kuanyin uses @nx/esbuild:esbuild for all libraries (not @nx/js:tsc):

Setting Value
Executor @nx/esbuild:esbuild
Output format ESM (format: ["esm"])
Bundling Disabled (bundle: false)
Output path dist/libs/kuanyin/{library}/ or libs/kuanyin/{library}/dist/

The esbuild executor provides faster builds compared to @nx/js:tsc. Output is unbundled ESM, meaning each source file is compiled individually.


Type Checking#

In addition to the standard build, lint, and test targets, all Kuanyin libraries include an explicit typecheck target that runs tsc --noEmit:

bash
pnpm nx typecheck kuanyin-foundation
pnpm nx typecheck kuanyin-precognition
pnpm nx typecheck kuanyin-cross-domain

This is separate from the build step because esbuild does not perform type checking. Always run typecheck before committing changes to catch type errors that esbuild would silently ignore.

Run Typecheck Across All Libraries#

bash
pnpm nx run-many --target=typecheck --projects=tag:scope:kuanyin

Testing#

Run Tests for a Single Library#

bash
pnpm nx test kuanyin-foundation
pnpm nx test kuanyin-database
pnpm nx test kuanyin-precognition
pnpm nx test kuanyin-mindful-friction
pnpm nx test kuanyin-performer-protection

Run All Kuanyin Tests#

bash
pnpm nx run-many --target=test --projects=tag:scope:kuanyin

Test Configuration#

All libraries use Vitest via the @nx/vite:test executor:

typescript
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    root: __dirname,
    passWithNoTests: true,
  },
});

Key differences from other domains:

  • passWithNoTests: true is set on the foundation library's vitest config, allowing the test target to pass even when no tests exist yet
  • root: __dirname explicitly sets the test root

Test Count#

The domain has 52 test files across all 10 libraries. Each module typically has a dedicated spec file. For example, kuanyin-precognition has 6 spec files: intent-analysis.spec.ts, cascade-prediction.spec.ts, typing-dynamics.spec.ts, context-awareness.spec.ts, behavioral-patterns.spec.ts, and emotional-detection.spec.ts.

Running Tests with Coverage#

bash
pnpm nx test kuanyin-precognition -- --coverage

Writing Tests#

Kuanyin tests focus on safety-critical behavior. Tests should cover edge cases thoroughly:

typescript
import { describe, it, expect } from 'vitest';
import { analyzeIntent, IntentAnalysisResult } from './intent-analysis.js';

describe('Intent Analysis', () => {
  describe('analyzeIntent', () => {
    it('should detect threatening language', () => {
      const result = analyzeIntent({
        message: 'test threatening content',
        context: { conversationHistory: [] },
      });
      expect(result.severity).toBe('high');
      expect(result.category).toBe('threats_violence');
    });

    it('should recognize benign content', () => {
      const result = analyzeIntent({
        message: 'hello, how are you?',
        context: { conversationHistory: [] },
      });
      expect(result.severity).toBe('negligible');
    });

    it('should handle empty input gracefully', () => {
      const result = analyzeIntent({
        message: '',
        context: { conversationHistory: [] },
      });
      expect(result.severity).toBe('negligible');
    });
  });
});

Testing Safety-Critical Code#

For harm detection and classification modules, always test:

  1. True positives - harmful content is correctly identified
  2. True negatives - benign content is not falsely flagged
  3. Edge cases - ambiguous content, empty input, Unicode, mixed languages
  4. Severity levels - correct severity assignment across all 6 levels
  5. Category coverage - all 50+ harm categories are testable

Linting#

bash
# Lint a single library
pnpm nx lint kuanyin-foundation

# Lint all Kuanyin libraries
pnpm nx run-many --target=lint --projects=tag:scope:kuanyin

Common Development Tasks#

Adding a New Module to an Existing Library#

For example, adding a new empathy-mapping module to kuanyin-mindful-friction:

  1. Create libs/kuanyin/mindful-friction/src/empathy-mapping.ts
  2. Create libs/kuanyin/mindful-friction/src/empathy-mapping.spec.ts
  3. Export from libs/kuanyin/mindful-friction/src/index.ts:
typescript
export * from './empathy-mapping.js';
  1. Verify:
bash
pnpm nx build kuanyin-mindful-friction
pnpm nx test kuanyin-mindful-friction
pnpm nx typecheck kuanyin-mindful-friction
pnpm nx lint kuanyin-mindful-friction

Adding a New Kuanyin Library#

  1. Create the directory structure under libs/kuanyin/{new-lib}/
  2. Create project.json using the esbuild executor:
json
{
  "name": "kuanyin-{new-lib}",
  "sourceRoot": "libs/kuanyin/{new-lib}/src",
  "projectType": "library",
  "tags": ["scope:kuanyin", "layer:domain"],
  "targets": {
    "build": {
      "executor": "@nx/esbuild:esbuild",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/libs/kuanyin/{new-lib}",
        "main": "libs/kuanyin/{new-lib}/src/index.ts",
        "tsConfig": "libs/kuanyin/{new-lib}/tsconfig.lib.json",
        "assets": [],
        "format": ["esm"],
        "bundle": false
      }
    },
    "test": {
      "executor": "@nx/vite:test",
      "outputs": ["{workspaceRoot}/coverage/libs/kuanyin/{new-lib}"],
      "options": {
        "config": "libs/kuanyin/{new-lib}/vitest.config.ts"
      }
    },
    "lint": {
      "executor": "@nx/eslint:lint",
      "outputs": ["{options.outputFile}"],
      "options": {
        "lintFilePatterns": ["libs/kuanyin/{new-lib}/**/*.ts"]
      }
    },
    "typecheck": {
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "tsc --noEmit --project libs/kuanyin/{new-lib}/tsconfig.lib.json"
        ]
      }
    }
  }
}
  1. Create package.json:
json
{
  "name": "@kuanyin/{new-lib}",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "devDependencies": {
    "vitest": "catalog:"
  }
}
  1. Run pnpm install.

Adding a New Harm Category#

When extending the harm classification system:

  1. Add the new HarmCategoryCode variant in libs/kuanyin/foundation/src/types.ts:
typescript
export type HarmCategoryCode =
  // ... existing categories
  'new_harm_category';
  1. Add severity and domain mapping in the constants file
  2. Update all detection modules that need to handle the new category
  3. Add tests for the new category across relevant modules

Implementing Cross-Domain Integration#

When adding Kuanyin ethics to a new Oshun domain:

  1. Create a new integration module in libs/kuanyin/cross-domain/src/:
typescript
// {domain}-integration.ts
export interface DomainEthicsConfig {
  enableContentModeration: boolean;
  enablePerformerProtection: boolean;
  severityThreshold: HarmCategorySeverity;
}

export function createDomainEthicsMiddleware(config: DomainEthicsConfig) {
  // Implementation
}
  1. Export from libs/kuanyin/cross-domain/src/index.ts
  2. The consuming domain adds @kuanyin/cross-domain as a dependency

Key Patterns and Conventions#

BuddhaNature Base Interface#

Every entity in the Kuanyin system implements the BuddhaNature interface:

typescript
interface BuddhaNature {
  readonly id: string;
  readonly compassionSeed: number;
  readonly wisdomFactor: number;
  readonly mindfulnessLevel: number;
  readonly karmaBalance: number;
  readonly innateGoodness: number;
  readonly awakeningPotential: number;
  readonly refugeStatus: RefugeStatus;
}

New entity types should extend this interface.

Severity Classification#

All harm assessments use the 6-level severity scale: negligible < low < moderate < high < severe < critical

Functions that score content should return one of these levels. The numeric mapping is consistent across all libraries.

Harm Category Domains#

Harm categories are organized into 10 domains: interpersonal, identity, safety, integrity, exploitation, manipulation, disruption, legal, platform, systemic. New harm categories should be assigned to the appropriate domain.

Buddhist-Informed Naming#

Module names draw from Buddhist terminology:

  • samma-vaca (Right Speech) in mindful-friction
  • dharma-analytics for community metrics
  • merit-karma for reputation systems
  • refuge-status for user progression stages

When naming new modules, prefer descriptive English names but consider Buddhist-inspired names where the concept maps directly to a Pali/Sanskrit term.

Compassionate Guardianship Principle#

Kuanyin's design philosophy is rehabilitation over punishment. When implementing moderation actions, always include:

  1. A path back (rehabilitation)
  2. An explanation (transparency)
  3. Proportional response (minimum necessary friction)

Debugging Tips#

esbuild vs tsc Type Checking#

Since Kuanyin uses esbuild (which strips types without checking them), you can have a successful build with type errors. Always run typecheck in addition to build:

bash
pnpm nx build kuanyin-foundation    # May succeed even with type errors
pnpm nx typecheck kuanyin-foundation # Will catch type errors

Import Path Extensions#

All imports must use .js extensions (ESM requirement):

typescript
// Correct
import { HarmCategoryCode } from './types.js';

// Incorrect
import { HarmCategoryCode } from './types';

Testing Scoring Functions#

Many Kuanyin modules compute scores (severity, merit, karma). When testing scoring functions, test boundary conditions:

typescript
describe('severityScoring', () => {
  it('should handle minimum score', () => {
    expect(scoreSeverity(0)).toBe('negligible');
  });
  it('should handle maximum score', () => {
    expect(scoreSeverity(1.0)).toBe('critical');
  });
  it('should handle threshold boundaries', () => {
    expect(scoreSeverity(0.2)).toBe('low');
    expect(scoreSeverity(0.4)).toBe('moderate');
  });
});

Foundation Type Changes#

Changes to kuanyin-foundation types propagate to all downstream libraries. After modifying foundation types, run the full typecheck and test suite:

bash
pnpm nx run-many --target=typecheck --projects=tag:scope:kuanyin
pnpm nx run-many --target=test --projects=tag:scope:kuanyin

Nx Project Name Lookup#

If you are unsure of a library's Nx project name, check the name field in its project.json. For Kuanyin, the naming convention is kuanyin-{library} without the @ prefix.


Project Configuration Reference#

Tags#

All Kuanyin libraries use: ["scope:kuanyin", "layer:domain"]

Executors#

Target Executor
build @nx/esbuild:esbuild
lint @nx/eslint:lint
test @nx/vite:test
typecheck nx:run-commands (tsc)

Environment Variables#

For kuanyin-database development:

bash
DATABASE_URL=postgresql://oshun:oshun_dev@localhost:5432/oshun_dev

No environment variables are needed for other Kuanyin libraries.