@ultrst-armada/krnl 1.0.2 → 1.0.3

package/README.md

@@ -1,96 +1,98 @@
-# Krnl Framework
+# KrnlTS
 
-> **Krnl**: Backend Service Framework for Skipo — a modular TypeScript framework for authoring, composing, executing, and validating backend services, facades, protocols, and workflows.
+KrnlTS is the backend semantic kernel for defining, validating, and running modular TypeScript services.
 
----
+## Architecture
 
-## 🚀 Overview
+```text
+KrnlTS
+├── packages/core      Service contracts, runtime, lifecycle, registry,
+│                      protocols, transports, state, events, discovery
+├── packages/validate  AST/static architecture and purity validation
+└── packages/cli       krnl command-line tooling
+```
 
-In the **Skipo** ecosystem, services are the foundational backend modules. **Krnl** provides the kernel architecture, lifecycle hooks, transport gateways, protocol decoders, and validation engine for building robust, decoupled backend services.
+`IMPLEMENTATION-SPEC.md` is the canonical architecture specification.
 
-- **Modular Service Architecture**: Define pure, stateful, and protocol-enabled backend service facades.
-- **Workflow & Flow Execution**: Compose multi-service pipelines and background execution boundaries.
-- **AST Purity & Validation**: Enforce 4-layer function purity, contract standards, and architecture rules via `ts-morph`.
-- **Protocol & Network Ingress**: Support REST, WebSocket, RPC, and MCP protocol bindings out of the box.
-- **Universal Backend Readiness**: Run seamlessly across Local FS, Local-Hosted, and Serverless environments.
+KrnlTS owns backend service semantics and framework tooling. It does not own downstream service catalogs, frontend libraries, application composition, or ecosystem orchestration.
 
----
+## Canonical Orchestration Boundary
 
-## 🚀 Quickstart: Starting a Fresh Workspace
+KrnlTS owns within-service functionality composition:
 
-### 1. Scaffold a New Project
-Run the official interactive project generator:
+```text
+KrnlTS
+  Service
+    ├── Functionality
+    └── FunctionalityOrchestration
+```
 
-```bash
-# Using npm
-npm create krnl my-service-app
+A `FunctionalityOrchestration` strictly composes internal functionalities belonging to a single service. It MUST NOT compose independent services.
+Cross-service orchestration (`ServiceOrchestration`) is owned exclusively by Skipo at the application/domain layer.
 
-# Using npx
-npx create-krnl my-service-app
+## Core service model
 
-# Using pnpm
-pnpm dlx create-krnl my-service-app
-```
+A service defines:
 
-This generates a fully configured Krnl backend workspace:
-- `krnl.json` (Workspace manifest & provider bindings)
-- `package.json` & `tsconfig.json`
-- `src/services/` (Backend service definitions & facades)
-- `src/libraries/` (Layer 0 pure concept libraries)
-- `docs/HISTORY.md` (Project intent & architectural memory)
+- identity and version
+- operations with input/output contracts
+- execution handlers
+- optional state
+- typed events
+- lifecycle hooks
+- dependencies, capabilities, and protocol metadata
 
----
+Public service construction is runtime-validated through the service generators.
 
-### 2. Run and Validate Services
+Lifecycle is an explicit state machine:
 
-```bash
-cd my-service-app
+```text
+uninitialized -> initializing -> ready -> starting -> running
+                                               |
+                                               v
+                                           stopping -> stopped
+```
 
-# Start Krnl service dev server
-krnl dev
+A stopped service may be restarted. Invalid lifecycle transitions fail deterministically.
 
-# Run deep AST 4-layer service purity validation
-krnl validate
+## Remote service contract
 
-# Build production bundle
-krnl build
-```
+`ServiceProxy` implements the same `IService` contract as a local service while operation execution is mediated by a `ProtocolAdapter`.
 
----
+Proxy lifecycle is local client lifecycle. Proxy state is a local cache and proxy events are local subscriptions unless a transport explicitly implements synchronization.
 
-### 3. CLI Commands Reference
+## Validation
 
-```bash
-# Start Krnl service dev server & boot service entrypoint
-krnl dev
+KrnlTS has two complementary validation layers:
 
-# Run deep AST 4-layer function purity audit
-krnl validate
+1. **Runtime contract validation** — validates service definitions and registration boundaries.
+2. **AST/static validation** — validates source architecture and purity rules through `@ultrst-armada/krnl-validate`.
 
-# Validate and build production bundle into dist/
-krnl build
+Both are part of the framework contract and require regression coverage.
+
+## CLI
 
-# Generate ambient TypeScript declarations for auto-discovery
-krnl watch
+The `@ultrst-armada/krnl-cli` package exposes:
 
-# Scaffold architectural primitives via CLI
-krnl generate entity UserSystem
-krnl generate functionality UserSystem CreateProfile
-krnl generate library BillingConcepts
-krnl generate subapp OrderEngine
+```bash
+krnl validate
+krnl build
+krnl dev
+krnl sync
+krnl generate <service|orchestration|functionality|library> <Name> [parentService]
 ```
 
----
+## Packages
 
-## 🏛️ Monorepo Framework Packages
+| Package | Purpose |
+|---|---|
+| `@ultrst-armada/krnl-core` | Canonical runtime and framework primitives |
+| `@ultrst-armada/krnl-validate` | AST/static validation |
+| `@ultrst-armada/krnl-cli` | CLI tooling |
+| `@ultrst-armada/krnl` | Root distribution package/export surface |
 
-- **[`@ultrst-armada/krnl`](packages/core)**: Core runtime engine, Service facades, Protocols, Transports, Registry, Lifecycle, and Execution flows.
-- **[`@dinilmusick/krnl-validate`](packages/validate)**: `ts-morph` AST engine enforcing 4-layer function purity, backend contracts, and line limits.
-- **[`@dinilmusick/eslint-plugin-krnl`](packages/eslint-plugin)**: ESLint rules with auto-fixers for Krnl backend service standards.
-- **[`@dinilmusick/krnl-cli`](packages/cli)**: Unified `krnl` binary for running, building, and validating backend services.
-- **[`create-krnl`](packages/create-krnl)**: Interactive project scaffolder for Krnl backend service modules.
+The legacy root `src/` tree is compatibility-only. Canonical implementations live under `packages/core/src`.
 
----
+## Acceptance
 
-## 📜 License
-MIT © Dinil Palackal
+A KrnlTS change is complete only when build, typecheck, tests, validation, CLI behavior, and public package exports pass, with no ownership leakage into downstream ecosystem layers.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ultrst-armada/krnl",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "private": false,
-  "description": "Krnl: Backend Service Framework for Skipo — authoring, executing, and validating modular backend services, facades, and workflows",
+  "description": "KrnlTS backend semantic kernel for authoring, validating, and running modular TypeScript services",
   "type": "module",
   "main": "./packages/core/dist/index.js",
   "module": "./packages/core/dist/index.js",
@@ -32,9 +32,7 @@
     }
   },
   "bin": {
-    "krnl": "./packages/cli/dist/bin/krnl.js",
-    "krnlts-watch": "./packages/cli/dist/bin/krnl.js",
-    "krnlts-validate": "./packages/cli/dist/bin/krnl.js"
+    "krnl": "./packages/cli/dist/bin/krnl.js"
   },
   "publishConfig": {
     "access": "public",
@@ -42,14 +40,14 @@
   },
   "scripts": {
     "build": "pnpm -r run build",
-    "test": "vitest run",
+    "test": "pnpm -r run test",
     "validate": "node packages/cli/dist/bin/krnl.js validate",
     "dev": "node packages/cli/dist/bin/krnl.js dev",
-    "watch": "node packages/cli/dist/bin/krnl.js watch"
+    "watch": "node packages/cli/dist/bin/krnl.js watch",
+    "typecheck": "pnpm -r run typecheck"
   },
   "keywords": [
     "krnl",
-    "skipo",
     "service-framework",
     "backend",
     "backend-modules",
@@ -64,8 +62,10 @@
   "devDependencies": {
     "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^25.6.0",
+    "@types/react": "^18.3.31",
     "better-sqlite3": "^13.0.3",
     "protobufjs": "^8.7.1",
+    "react": "^18.3.1",
     "tsup": "^8.4.0",
     "turbo": "^2.4.4",
     "typescript": "^5.7.3",
@@ -73,5 +73,9 @@
     "ws": "^8.20.0",
     "zod": "3.24.1",
     "zod-to-json-schema": "3.24.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dinilmusick/KrnlTS.git"
   }
 }