Promise System

promise-system is a TypeScript backend library for Promise Protocol-style agents, promises, assessments, registry events, reasoner charters, and merit tracking.

The project is structured using a layered, domain-driven design:

• src/domain: core entities, domain services, and rules
• src/application: use cases and orchestration
• src/infrastructure: persistence and crypto adapters
• src/interfaces: thin adapters for CLI, REST API, and web-facing consumers
• features: executable BDD specifications

Architectural Rules

This repository follows two strict boundaries:

• BDD scenarios touch only the application layer.
• Any interface implementation must interact with the system only through the application layer.

That means the application service is the system boundary. Domain and infrastructure code are exercised indirectly from features and directly from lower-level tests.

Capabilities

The current system supports:

• agent creation and public-key-derived addresses
• intentions and signed promises
• agent state creation, registration, and forward resolution
• promise assessments and merit calculation
• human and AI reasoners
• generic reasoner charters and ABDUCTIO-specific charters
• inheritance/classification rules without cycles
• multiple interface adapters over the same application boundary
• in-memory and Supabase-backed persistence

Project Structure

src/
  application/
  domain/
  infrastructure/
  interfaces/
features/
supabase/

Key entrypoints:

• src/index.ts
• src/application/index.ts
• src/application/createPromiseSystemApplication.ts
• src/application/PromiseSystemApplication.ts

Package Contract

Consumers should import only from the package root:

• createPromiseSystemApplication
• PromiseSystemApplication
• public DTO and input/output types
• PromiseSystemWebAdapter for server-side web integration

The root export intentionally hides domain and infrastructure internals.

Using as a Package From a Web App

npm install promise-system

Apply the schema in supabase/schema.sql, then instantiate the application on the server side:

import {
  PromiseSystemWebAdapter,
  createPromiseSystemApplication
} from 'promise-system';

const app = createPromiseSystemApplication({
  backend: 'Supabase',
  supabase: {
    url: process.env.SUPABASE_URL,
    key: process.env.SUPABASE_SERVICE_ROLE_KEY,
    schema: process.env.SUPABASE_SCHEMA
  }
});

app.bootSystem();

const promiseSystem = new PromiseSystemWebAdapter(app, {
  interfaceName: 'Lovable Web App'
});

await promiseSystem.connectAgent('Marin Ortega');
await promiseSystem.publishReasonerCharter('Marin Ortega');
await promiseSystem.createPromise(
  'Marin Ortega',
  'I will cite evidence for decisive claims.',
  'R-TRACE'
);

Keep this package on the server side. UI code should call server actions, route handlers, or API endpoints that delegate to the application layer.

Build and Publish

The package builds to dist/ and exposes a root export only:

• dist/index.js
• dist/index.d.ts

Build locally:

npm install
npm run build

The build is produced by the repository itself and emits a reusable package surface without requiring an external bundler. The package is ready to publish to npm, GitHub Packages, or to be installed directly from a GitHub repository once the repo exists remotely.

Supabase Backend

If backend is set to Supabase but no URL and key are configured, the factory falls back to an in-memory Supabase transport. That is useful for tests and local integration wiring, but production deployments should provide real Supabase credentials.

Building a Web Product on Top

If you are building a sensemaking website with a web UI, treat this project as the backend domain/application package rather than the full web app.

Recommended approach:

• keep all writes behind server-side code
• instantiate PromiseSystemApplication in your backend routes or server actions
• use the application layer as the only write boundary
• expose read-optimized projections for the frontend when needed
• keep browser-authenticated access separate from protocol persistence concerns

A typical shape is:

• web app: Next.js or another server-capable web framework
• protocol backend: this project
• persistence: Supabase
• auth and product-facing reads: handled by the host web app

Developing This Repo

The test suite is centered on executable BDD features and uses Node's built-in test runner.

npm test

npm test runs both:

• the source-level BDD and application/infrastructure test suite
• a built-package end-to-end smoke test against dist/index.js

Coverage:

npm run test:bdd:coverage

Type-check:

npm run typecheck

Note: the test scripts currently rely on Node's --experimental-transform-types support to execute TypeScript directly.

BDD and DDD Integration

The feature suite is intentionally written at the application boundary. That keeps the scenarios interface-agnostic and backend-agnostic:

• step definitions call application use cases
• interface adapters remain thin
• infrastructure can be swapped without changing feature intent

This is the contract the repository is designed to preserve.

Current Interfaces

The codebase includes adapters for:

• CLI
• REST API
• Web UI
• Lovable Web App
• package-root PromiseSystemWebAdapter

These adapters are intentionally thin and delegate to application services rather than implementing business logic themselves.

Supabase Schema

The Supabase schema includes tables for:

• agents
• states
• agent heads
• promises
• assessments
• registered agents
• events

See supabase/schema.sql.

Status

This repository currently provides the protocol/application backend, BDD specifications, and a Supabase persistence path. It does not include a full production web frontend or a complete HTTP server runtime out of the box; those are intended to be composed on top of the application layer.