@aibos/kernel

The Business Constitution (L0 SSOT)

Overview

@aibos/kernel is the Single Source of Truth (SSOT) for all platform metadata in AI-BOS. It defines:

• 30 Concepts - What business objects exist (Entity, Attribute, Operation, Relationship)
• 12 Value Sets - Allowed value collections
• 62 Values - The actual allowed values

If it's not defined in @aibos/kernel, it doesn't exist in AI-BOS.

Installation

npm install @aibos/kernel
# or
pnpm add @aibos/kernel

Usage

import {
  // Concepts (30)
  CONCEPT,
  ConceptId,
  CONCEPT_CATEGORY,

  // Value Sets (12)
  VALUESET,
  ValueSetId,

  // Values (62)
  VALUE,

  // Version
  KERNEL_VERSION,
  SNAPSHOT_ID,
} from "@aibos/kernel";

// Type-safe concept usage
const invoiceConcept = CONCEPT.INVOICE; // "CONCEPT_INVOICE"
const vendorConcept = CONCEPT.VENDOR; // "CONCEPT_VENDOR"

// Type-safe value usage
const currency = VALUE.CURRENCIES.MYR; // "CURRENCY_MYR"
const status = VALUE.APPROVAL_ACTION.APPROVED; // "APP_APPROVED"
const country = VALUE.COUNTRIES.MALAYSIA; // "COUNTRY_MY"

// Value set references
const currencySet = VALUESET.CURRENCIES; // "VALUESET_GLOBAL_CURRENCIES"

Architecture

L0 Kernel (Constitutional) ← @aibos/kernel
    │
    ├─► L1 Domain Canon    ← @nexus/canon-claim, @nexus/canon-vendor
    │
    ├─► L2 Cluster         ← Workflows, Approvals
    │
    └─► L3 Cell            ← UI, API, Runtime

Truth flows ONE-WAY. Downstream may restrict but never redefine.

Exports

Concepts

| Category | Count | Examples | | ------------ | ----- | ------------------------------------- | | ENTITY | 12 | INVOICE, VENDOR, CLAIM, DOCUMENT | | ATTRIBUTE | 6 | STATUS, PRIORITY, RISK, IDENTITY | | OPERATION | 8 | APPROVAL, AUDIT, PAYMENT, WORKFLOW | | RELATIONSHIP | 4 | GROUP_MEMBERSHIP, VENDOR_COMPANY_LINK |

Value Sets

| Value Set | Count | Example Values | | --------------- | ----- | ----------------------------- | | APPROVAL_ACTION | 5 | SUBMITTED, APPROVED, REJECTED | | CURRENCIES | 5 | USD, EUR, MYR, SGD, GBP | | COUNTRIES | 4 | MALAYSIA, SINGAPORE, US, UK | | DOCUMENT_TYPE | 9 | INVOICE, PO, GRN, CONTRACT | | STATUS_GENERAL | 4 | ACTIVE, INACTIVE, SUSPENDED | | WORKFLOW_STATE | 5 | DRAFT, PENDING, IN_REVIEW |

Validation

import {
  validateKernelIntegrity,
  KERNEL_VERSION,
  SNAPSHOT_ID,
} from "@aibos/kernel";

// Throws if counts don't match expected
validateKernelIntegrity();

console.log(`Kernel v${KERNEL_VERSION} (${SNAPSHOT_ID})`);

CI Integration

The registry.snapshot.json file is embedded in the package and should be used for:

1. DB Validation - Compare DB contents against snapshot
2. Drift Detection - CI fails if DB diverges from snapshot
3. Version Verification - Ensure kernel_metadata table matches

License

MIT