anbaric-tsapi

The contracts and value classes shared by every Anbaric package. Nothing here depends on any other Anbaric package. App developers usually install anbaric instead, which re-exports all of this.

Interfaces whose implementations may cross a process boundary are async: their methods return Promise even when an implementation is trivially synchronous.

Value classes

Job — a unit of work moving through a workflow. Immutable. new Job(id, properties = new Map(), state, workflowId?, startedBy = "system", startedAt = new Date(), lastUpdated = startedAt). state is a readonly string; a job never changes in place — JobPersistence.save constructs a new Job at the target state and stamps lastUpdated.

State — new State(id, actions = [], transitions = []), plus subscribe(action) to add an action later.

Action — new Action(name, actor, description = "", id = crypto.randomUUID()). Two replaceable function fields: predicate : (job) => boolean (defaults to accept) gates whether the action runs, and run : (job) => Promise<Map<string, any>> (defaults to an empty map) returns the property changes the action wants. run never mutates the job.

Actor — an interface, pure identity: { type : "HUMAN" | "CODE" | "AGENT" | "SYSTEM", id : string, role : string }. Concrete Human, Code, Agent classes live in anbaric-state-machine.

Transition — new Transition(to, predicate); the first accepting transition in a state wins.

PropertyDefinition — new PropertyDefinition(id) with mutable required : boolean (default false) and validation : (value) => boolean (default accept).

Serialization — serializeJob(job) : SerializedJob and deserializeJob(serialized) : Job define the wire shape used by the cloud clients and platform (dates as ISO strings, properties as a plain object).

Contracts

JobPersistence — an abstract class taking an Auditor; every method takes the acting Actor and audits before deferring to an abstract …Internal. create(actor, job), save(actor, changeDescription, job, properties?, state?) (applies the property/state change and stamps lastUpdated), retrieve(id, actor) (throws No job found with id "x"), delete(id, actor), list(actor, pageSize?, page?).

Queue — enqueue(jobId, workflowId), schedule(jobId, workflowId, due). Dequeue extends Queue adds dequeueSome() : Promise<Array<QueueMessage>>; the exported Dequeue.supports(queue) type guard tests for it structurally. Delivery is at-least-once: consumers must tolerate redelivery.

Consumer — subscribe(workflowId, processJob) routes deliveries for one workflow to a callback; cleanUp() releases resources.

JsonStore — abstract, Auditor-backed and actor-audited like JobPersistence: create(actor, id, document), save(actor, changeDescription, id, document), retrieve(id, actor), delete(id, actor), list(actor, pageSize?, page?) (returns the document values, not ids); implementations validate against a JsonSchema when one is given.

SecretStore — abstract, Auditor-backed: create(actor, name, value), save(actor, changeDescription, name, value), retrieve(name, actor), delete(name, actor), list(actor). Secret values never appear in audit details.

QueueMessage — { jobId, workflowId }; part of the platform's private wire protocol (in api/cloud/), exported because Dequeue returns it.