npm package: @garrick0/c2-core-domain
Description: C2 Core Domain - Pure domain types for the check system
Author: garrick0
Latest version: 6.1.0

# @garrick0/c2-core-domain

> Pure domain types and stateless functions for the C2 check system.

## Overview

This package contains the **domain layer** of the C2 microkernel architecture. It defines the core abstractions for the check system with zero external dependencies.

## Installation

```bash
npm install @garrick0/c2-core-domain
```

## Key Concepts

### Observable

A versioned, immutable snapshot of observed state with query capability.

```typescript
interface Observable<TData> {
  readonly id: ObservableId;      // { type: 'git-branch', key: '/path' }
  readonly version: number;
  readonly timestamp: Date;
  readonly data: TData;
  query(params: QueryParams): QueryResponse;
}
```

### CheckDefinition

A declarative specification of a check that runs against an Observable.

```typescript
interface CheckDefinition {
  id: string;                    // 'git:no-protected-branch'
  name: string;                  // 'No Protected Branch'
  observableType: string;        // 'git-branch'
  query: QueryParams;            // { operation: 'branchIsProtected' }
  mustBe: boolean;               // Expected query result
  message: string | ((response, observable) => string);
  defaultSeverity?: ViolationSeverity;
}
```

### CheckRunner

Executes checks against Observables and returns results.

```typescript
const runner = createCheckRunner();
const result = runner.runOne(observable, activeCheck);
// { checkId, passed, violation?, response, ... }
```

## API Reference

### Types

| Type | Description |
|------|-------------|
| `Observable<TData>` | Versioned snapshot with query capability |
| `ObservableId` | `{ type: string, key: string }` |
| `QueryParams` | `{ operation: string, ...params }` |
| `QueryResponse<T>` | `{ ok: boolean, data: T, message? }` |
| `CheckDefinition` | Declarative check specification |
| `CheckConfigEntry` | Configuration for a check |
| `ActiveCheckDefinition` | CheckDefinition resolved with config |
| `CheckResult` | Result of running a single check |
| `CheckBatchResult` | Result of running multiple checks |
| `Violation` | Represents a failed check |
| `ViolationSeverity` | `'error' \| 'warning' \| 'info'` |
| `Result<T, E>` | Functional error handling type |

### Functions

```typescript
// CheckDefinition resolution
resolveCheckDefinition(definition, configEntry?): ActiveCheckDefinition | null
resolveCheckDefinitions(definitions, configMap): ActiveCheckDefinition[]

// CheckRunner
createCheckRunner(): ICheckRunner

// Result utilities
ok(value): Result<T, never>
err(error): Result<never, E>
isOk(result): result is Ok<T>
isErr(result): result is Err<E>
map(result, fn): Result<U, E>
flatMap(result, fn): Result<U, E>
mapError(result, fn): Result<T, F>
unwrapOr(result, defaultValue): T
combine(results): Result<T[], E>
tryCatch(fn): Result<T, Error>
asyncTryCatch(fn): Promise<Result<T, Error>>
```

## Usage Example

```typescript
import {
  createCheckRunner,
  resolveCheckDefinition,
  type Observable,
  type CheckDefinition,
} from '@garrick0/c2-core-domain';

// Create a mock observable
const observable: Observable<{ value: number }> = {
  id: { type: 'test', key: 'example' },
  version: 1,
  timestamp: new Date(),
  data: { value: 42 },
  query(params) {
    if (params.operation === 'isAbove') {
      const threshold = (params.threshold as number) ?? 0;
      return { ok: this.data.value > threshold, data: { value: this.data.value } };
    }
    return { ok: false, data: null };
  },
};

// Define a check
const checkDef: CheckDefinition = {
  id: 'test:value-above-10',
  name: 'Value Above 10',
  observableType: 'test',
  query: { operation: 'isAbove', threshold: 10 },
  mustBe: true,
  message: 'Value must be above 10',
  defaultSeverity: 'error',
};

// Resolve and run
const activeCheck = resolveCheckDefinition(checkDef);
if (activeCheck) {
  const runner = createCheckRunner();
  const result = runner.runOne(observable, activeCheck);
  console.log(result.passed);  // true (42 > 10)
}
```

## Architecture

This package is the innermost layer of the C2 architecture:

```
c2-cli → c2 → core-application → core-domain (this package)
                    ↓
           observable-git (plugin)
```

It has **no dependencies** on other packages and contains only:
- Type definitions
- Pure functions
- Stateless services

## Development

```bash
# Build
npx nx build @garrick0/c2-core-domain

# Test
npx nx test @garrick0/c2-core-domain

# Lint
npx nx lint @garrick0/c2-core-domain
```

## License

MIT