tom_core_kernel

> Attribution. The Tom Framework is developed by Peter Nicolai Alexis Kyaw. > These packages are proprietary and internal (publish_to: none).

Core kernel library for the Tom Framework — the platform-neutral building blocks every other Tom layer is composed from.

Overview

tom_core_kernel is the foundation of the Tom Framework. It carries no UI and no server runtime, so it runs unchanged on any Dart target — CLI, server, Flutter, or the d4rt interpreter. Everything layered above it (the server stack, the Flutter / UI layers, the DartScript bridge) depends on the contracts defined here.

The kernel is reflection-aware: it builds on tom_reflection so observable objects, security principals, and resource trees can be introspected and serialized without hand-written boilerplate. Conceptually it provides five things:

• Observable state — values and objects that notify observers on change, with

a terse operator syntax (| set, ~ read, >> observe). - Ambient context — zone-propagated execution context and hierarchical scope identifiers, so a deeply nested call can resolve "where am I" without threading parameters through every frame. - Dependency injection — a reflection-driven bean container. - Security — authentication, a layered access-control model, bearer-token auth, and a four-state authorization model (TomAuthState). - Runtime utilities — logging (including isolate/remote), an isolate worker pool, JSON tree helpers, resource providers, settings, timezone-aware timestamps, and ordered shutdown.

Installation

This package is internal to the Tom workspace and consumed by path (it is publish_to: none), so there is no dart pub add line. Add it as a path dependency:

dependencies:
  tom_core_kernel:
    path: ../tom_core_kernel

Then import the single barrel:

import 'package:tom_core_kernel/tom_core_kernel.dart';

The barrel re-exports tom_basics, tom_crypto and tom_reflection, so one import covers the common surface. SDK: Dart ^3.10.0. Modules that use reflection require a dart run build_runner build to generate *.reflection.dart.

Features

Observable state (observable)

Type	Responsibility
TomObject<T>	Base observable holding a single typed value
TomString / TomInt / TomDouble / TomBool	Typed scalar observables
TomClass / TomList / TomMap	Observable composites

Context & scope (context, scope_ids)

Type	Responsibility
TomExecutionContext	Ambient, zone-propagated execution context
TomContextEntry<T>	A typed value carried on the context
TomScope / InScopeBuilder	Hierarchical, zone-propagated scope identifiers

Dependency injection (beanlocator)

Type	Responsibility
TomComponent	A registrable framework component
TomBean<T>	A located/injected bean instance

Security (security)

Type	Responsibility
TomAuthorization / TomAuthState	Authorization decisions and the four-state model
TomAccessControl (+ TomNoAccess , TomPublicAccess , TomAuthenticatedAccess , TomGuestAccess )	Layered access-control rules
TomBearerAuthentication	Bearer-token authentication
TomAccessControlInformation , TomGroup , TomRole , TomEntitlement	Principal / ACI model

Runtime utilities

Module	Key types	What it does
logging	isolate & remote log output/server	Structured logging across isolates and the wire
isolate_pooling	TomWorker , TomWorkerPool , TomExecutor , TomCommand	Worker-pool execution across isolates
json	map-merge, pretty-print helpers	JSON tree merge/serialization utilities
resources	TomTextResourceProvider, TomConfigResourceProvider	Text and configuration resource resolution
settings	client settings/authorization	Settings management
shutdown_cleanup	TomShutdownCleanup, TomDisposable, TomClosable	Ordered shutdown / cleanup hooks
timezoned	DateTimestamp, timezone tables	Timezone-aware date/time
http_connection	server connection, endpoints, headers	HTTP connection helpers
little_things	zone helpers, formatting, TomException	Small cross-cutting utilities
reflection	reflection bootstrap	Reflection support built on tom_reflection

Quick start

Observable state with automatic observer propagation:

import 'package:tom_core_kernel/tom_core_kernel.dart';

void main() {
  final count = TomInt(0);
  count >> (obs) => print('changed to ${~count}');
  count | 5; // prints: changed to 5
}

| sets the value, ~ reads it, and >> registers an observer that fires on every change.

Example projects

Every module ships a runnable sample folder under example/, and a top-level run_all_samples.dart runs them all.

Sample	Demonstrates
example/observable/	Observable scalars, composites, and observers
example/beanlocator/	Registering and locating beans
example/context/	Execution context & context entries
example/scope_ids/	Hierarchical scope paths
example/security/	Access controls, authorization, bearer auth
example/crypto/	JWT / hashing helpers (via tom_crypto)
example/isolate_pooling/	Worker-pool execution
example/logging/	Structured / isolate / remote logging
example/resources/	Text & config resource providers
example/json/ · example/timezoned/ · example/settings/ · example/shutdown_cleanup/ · example/http_connection/ · example/little_things/ · example/reflection/	The remaining utility modules

Run the whole set:

dart run build_runner build      # generate reflection (once / on signature change)
dart run example/run_all_samples.dart

> Cross-package sample. Beyond these per-module examples, the shared > tom_core_samples/todo_domain project (forthcoming) models one > todo-management domain on this kernel's reflection — the single entity set > every Tom Core sample reuses. See the > samples map for the full learning path.

Usage

Namespacing with zone-propagated scopes

TomScope.withScope('checkout', () {
  TomScope.withScope('orderForm', () {
    print(TomScope.current.getScopePath()); // checkout.orderForm
  });
});

Resolving text resources

TomTextResourceProvider.setAppResourceProvider(
  TomTextResourceProvider.from({'greeting': 'Hello, {name}!'}),
);

Locating a bean

Components are registered as TomComponents and resolved as TomBean<T>s through the locator — the container wires dependencies by reflected type rather than by manual construction.

Ordered shutdown

TomShutdownCleanup registers TomDisposable / TomClosable resources and tears them down in a deterministic order on process exit.

Architecture

                tom_core_kernel
                      │
   ┌──────────┬───────┼────────┬───────────┐
observable  context  security  resources   runtime utils
 (TomObject) (scope) (TomAuth*) (providers) (logging, isolates,
                                             json, settings,
                                             shutdown, timezoned)
                      │
              tom_reflection  ← introspection / serialization
              tom_basics · tom_crypto

The kernel is a single package with one barrel; modules live under lib/src/tombase/<module>/ and are mutually low-coupled — context/scope and observable underpin the rest, security builds on both, and the runtime utilities are largely independent.

Type	Responsibility
TomObject<T>	Observable value, the unit of reactive state
TomScope	Zone-propagated hierarchical scope identifier
TomExecutionContext	Ambient context carried through a call tree
TomAuthorization / TomAuthState	Authorization decision + four-state model
TomAccessControl	Base access-control rule
TomBean<T> / TomComponent	DI bean / registrable component
TomWorker / TomWorkerPool	Isolate worker-pool execution
TomTextResourceProvider	Text resource resolution
TomShutdownCleanup	Ordered teardown registry

Ecosystem

tom_basics · tom_crypto · tom_reflection
                 │
          tom_core_kernel        ← you are here
        ┌────────┼─────────┐
tom_core_server  tom_core_flutter  tom_core_d4rt
                 │                   (bridges the kernel into d4rt scripts)
          tom_flutter_ui

tom_core_kernel sits directly on the basics/crypto/reflection foundation and is the common dependency of the server, Flutter, and DartScript layers. See the repository map for the full picture.

Further documentation

• Per-module guides under doc/ — one folder per module

(doc/observable/, doc/security/, doc/scope_ids/, …). - tom_core_server — the server runtime built on this kernel. - tom_core_flutter / tom_flutter_ui — the client/UI layers. - tom_core_d4rt — exposes these types to d4rt scripts.

Status

• Version: 1.1.0
• Tests: 1,464 test cases across 17 module suites (run with testkit :test

or dart test). - License: proprietary — see LICENSE.