@m4ike1/chord

Application-composition runtime for systems assembled from plugins: facets, services (singleton and keyed), replicated state, and a pluggable remote-service boundary.

Chord is developed in the Ion monorepo but is not an Ion package: it has no dependency on any other Ion workspace package and can be used by unrelated applications. The only runtime dependency is esbuild, used by the facet bundler.

Entrypoints

| Import | Contents | |---|---| | @m4ike1/chord | Facets, services, bindings, replicated state, wire helpers, errors | | @m4ike1/chord/context | Invocation context (cancellation, scoped values) | | @m4ike1/chord/delta | Standalone JSON change-tracking primitive | | @m4ike1/chord/bundler | Facet bundler (bundleFacets, bundleFacetPackage) | | @m4ike1/chord/node | Node-only facet bundle loaders |

Minimal example

import { createFacetHost, defineFacet, defineService } from "@m4ike1/chord";
import { BACKGROUND_CONTEXT } from "@m4ike1/chord/context";
import type { Context } from "@m4ike1/chord";

interface Greeter {
	greet(name: string, ctx: Context): Promise<string>;
}

const GreeterService = defineService<Greeter>("example.greeter");

const provider = defineFacet({
	id: "example.greeter-impl",
	setup(env) {
		env.provide(GreeterService, {
			greet: async (name) => `hello ${name}`,
		});
	},
});

const consumer = defineFacet({
	id: "example.consumer",
	setup(env) {
		const greeter = env.use(GreeterService);
		env.onActivate(async () => {
			console.log(await greeter.greet("ion", BACKGROUND_CONTEXT));
		});
	},
});

const host = await createFacetHost({ facets: [provider, consumer] });
// ... later
await host.dispose();

Rules visible here: setup is synchronous declaration only (no service calls during setup); the host validates the graph, binds services, and activates providers before consumers.

Constraints that apply everywhere

• Remote service arguments, results, snapshots, and updates must be finite strict JSON (null for absence, never undefined). Process-local services (declared with { local: true }) accept unrestricted contracts but are never published remotely.
• Service IDs beginning with $chord. are reserved. $chord.service is the control service used for catalogue and subscription calls.
• Import context constants and functions from @m4ike1/chord/context; their generic names do not pollute the root API.

Docs

• docs/facets.md — facets, hosts, loaders, lifecycle, reload
• docs/services.md — service tokens, singleton/keyed modes, contracts, facades
• docs/state-delta.md — replicated state and the delta primitive
• docs/remote.md — provider, endpoint, transport adapters, bindings, wire helpers
• docs/bundling.md — bundling facet packages and loading them on Node
• docs/context.md — invocation context and cancellation
• docs/reference.md — per-entrypoint API inventory