Cadenza DB

Overview

Cadenza is an innovative framework that extends traditional orchestration with event-driven choreography, providing "structured freedom" for building distributed, self-evolving systems.

The core package (@Cadenza.io/core) includes the foundational primitives for defining and executing graphs of tasks, managing contexts, handling signals, and bootstrapping executions. It's designed to be language-agnostic in model, with this TypeScript implementation serving as the reference.

Cadenza's design philosophy emphasizes:

• Structured Freedom: Explicit graphs for dependencies (orchestration) combined with signals for loose coupling (choreography).
• Meta-Layer Extension: A self-reflective layer for monitoring, optimization, and auto-generation, enabling AI-driven self-development. Essentially extending the core, using the core.
• Introspectability: Exportable graphs, traceable executions, and metadata separation for transparency and debugging.
• Modularity: Lightweight core with extensions (e.g., distribution, UI integration) as separate packages.

The core is suitable for local dynamic workflows using tasks and signals. But thanks to the meta layer, it also serves as the foundation for the distributed, agentic AI applications, and more, abstracting complexities like networking and security in extensions.

Installation

Install the DB package via npm:

npm install @cadenza.io/cadenza-db

Usage

Creating Tasks

Tasks are the atomic units of work in Cadenza. They can be chained to form graphs.

import Cadenza from '@cadenza.io/service';

const task1 = Cadenza.createTask('task1', (context) => {
  console.log(context.foo);
  return { bar: 'baz' };
}, 'First task');

const task2 = Cadenza.createTask('task2', (context) => {
  return {...context, qux: 'quux'};
}, 'Second task');

const task3 = Cadenza.createTask('task3', (context) => {
  return {...context, cadenza: 'is awesome'};
}, 'Third task');

task1.then(
  task2.then(
    task3
  ),
);

Creating Routines

Routines are named entry points to graphs.

const routine = Cadenza.createRoutine('myRoutine', [task1], 'Test routine');

Running Graphs

Use a Runner to execute routines or tasks.

const runner = Cadenza.runner;
await runner.run(routine, {foo: 'bar'});

Signals

Signals provide event-driven coordination.

task1.emits('my.signal');
task2.doOn('my.other.signal');

Cadenza.broker.emit('my.other.signal', {foo: 'bar'}); // This will trigger task2

Using the Meta Layer

The meta layer serves as a tool for extending the core features. It follows the same rules and primitives as the user layer but runs on a separate meta runner. It consists of MetaTasks, MetaRoutines and meta signals. To trigger a meta flow you need to emit a meta signal (meta.[domain].[action]).

Cadenza.createTask('My task', (ctx) => {
  console.log(ctx.foo);
  return ctx;
}).emits('meta.some.signal'); // Emits a on task execution

Cadenza.createMetaTask('My meta task', (ctx) => {
  console.log(ctx.__task.name);
  return true;
}).doOn('meta.some.signal');

Cadenza.broker.emit('meta.some.signal', {foo: 'bar'}); // Trigger from anywhere

For full examples, see the docs folder or the test suite.

Features

• Graph-Based Orchestration: Define tasks and routines with chaining for dependencies, failovers, and layering.
• Event-Driven Choreography: Signals for loose coupling, with meta-signals for self-management.
• Context Management: Immutable contexts with metadata separation and schema validation.
• Execution Engine: Sync/async strategies, throttling, debouncing, and unique merging.
• Bootstrapping: Lazy initialization with seed tasks for registry and signal handling.

Architecture Overview

Cadenza's core is divided into:

• Definition Layer: Task, Routine for static graphs.
• Execution Layer: Node, Layer, Builder, Run for runtime.
• Signal Layer: SignalBroker, SignalParticipant for coordination.
• Context Layer: GraphContext for data flow.
• Registry Layer: GraphRegistry for introspection.
• Factory: Cadenza for creation and bootstrap.

Actor MVP Schema

The current actor minimum in cadenza-db is:

• actor: actor definition registry.
• actor_task_map: actor-task association registry.
• actor_session_state: durable state by (actor_name, actor_version, actor_key, service_name).

Important contract rule:

• Metadata payloads must match table field identities for validation and inserts to succeed.
• Naming style conversion (for example snake/camel) is handled in transport; field identity is what must remain consistent.

Current actor metadata signals used for sync:

• global.meta.graph_metadata.actor_created -> actor
• global.meta.graph_metadata.actor_task_associated -> actor_task_map
• strict write-through session persistence path:
  • core inquiry intent meta-actor-session-state-persist
  • service responder upsert into actor_session_state with durable-version stale-write guard

Design constraints:

• Actor type classification is is_meta (no kind column).
• Runtime-only objects are not persisted.
• Durable state persists through actor_session_state.durable_state.

Layer-Scoped Tools Persistence

cadenza-db now persists helper/global structural data and tool dependency closures.

Structural tables:

• helper
• global_registry

Direct dependency maps:

• task_to_helper_map
• helper_to_helper_map
• task_to_global_map
• helper_to_global_map

Transitive snapshot tables:

• task_tool_dependency_snapshot
• helper_tool_dependency_snapshot

Key contract rules:

• direct rows preserve the declared alias so runtime-visible tool keys stay reconstructable
• snapshot rows are materialized from direct edges and stay out of service_manifest
• helper/global payloads remain structural metadata, not routing membership

Contributing

Contributions are welcome! Please fork the repo, create a branch, and submit a PR. Follow the code style and add tests for new features.

License

MIT License

Copyright (c) 2025 Cadenza.io

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.