@axion-io/core

Framework-agnostic TypeScript core for the Axion Systems event-driven backend architecture.

Exposes the complete contract layer, port interfaces for all architecture components, use-case and handler base classes, lifecycle guards, schema validation, and in-memory fakes in @axion-io/core/testing. All APIs are stable and production-ready.

Contract layer

• JSON-compatible identity aliases for operations, messages, correlation, ordering, schema versions, and tenants.
• Durable domain-event envelopes and Task envelopes.
• Operation readiness and requirement unions.
• Actor references, capability requests, authorization evidence, and capability decisions.
• Adapter result normalization contracts.
• AxionContractError for durable diagnostics.

Port interfaces

• PolicyValidator<TContext> and AuthorizationResolver<TContext> for capability decisions.
• CommandUseCase, QueryUseCase, SystemUseCase, and TaskUseCase for all UseCase categories.
• CommandService, QueryService, SystemService, and TaskService for command, read, system, and task service boundaries.
• ProjectionHandler, TaskHandler, and SystemTriggerHandler for mapping triggers to domain logic.
• ProjectionMaterializer for projection write materializers that return discriminated ProjectionReport values from explicit materialization methods.
• Adapter<TInput, TValue> for normalized external side-effect results.
• OperationManager with typed input DTOs for all readiness lifecycle transitions.
• OutboxWriter for durable domain-event and task publication.
• MutationResponse<TResult> for standard CommandUseCase return shapes with operation tracking.

Testing harnesses (@axion-io/core/testing)

• TestClock interface and createFixedClock(timestamp) for deterministic time in tests.
• InMemoryOperationManager implementing OperationManager with full readiness lifecycle, terminal state protection, and idempotent duplicate handling.
• InMemoryOutboxWriter implementing OutboxWriter with inspectable domainEvents and tasks arrays.
• FakePolicyValidator<TContext> implementing PolicyValidator with configurable allow/deny and call recording.
• FakeAdapter<TInput, TValue> implementing Adapter with configurable response and call recording.
• buildDomainEventEnvelope and buildTaskEnvelope builders with stable defaults and per-field overrides.

Runtime utilities (@axion-io/core)

• AbstractPolicyValidator<TContext> — base class that composes AuthorizationResolver evidence in parallel and delegates the final allow/deny decision to the abstract authorize(evidence, request) method.
• buildMutationResponse(operation, result, requiredProjectionNames?) — constructs MutationResponse<TResult> from an accepted Operation, computing requiresRefresh, requiredProjections, and correlationId automatically.

Projection testing tools (@axion-io/core/testing)

• FakeProjectionMaterializer<TInput> — implements ProjectionMaterializer and exposes execute(input) with a configurable ProjectionReport response. setReport(report) switches to a new report (also clears failure); failWith(error) switches to rejection mode; reset() clears calls and failure; callCount/calls inspection.
• buildProjectionCompletedReport(overrides?) — constructs ProjectionCompletedReport with stable defaults; every field overridable.
• buildProjectionFailedReport(overrides?) — constructs ProjectionFailedReport with stable defaults including failureCode and failureMessage.

AbstractAuthorizationResolver (@axion-io/core)

• AbstractAuthorizationResolver<TContext> — base class implementing AuthorizationResolver<TContext>. Constructor receives a readonly ActorCategory[] supported-categories list; supports() returns true iff the request's actor category is in that set. Subclasses implement only resolve(). Enforces the architecture convention that each resolver is scoped to one or more actor categories (user, system, admin, group, role).

Schema validation and authorization testing tools

• assertSchemaVersion(actual, expected) (@axion-io/core) — throws AxionContractError("unsupported_schema_version") with { actual, expected } metadata when versions differ. The standard tool for validateEnvelope implementations in AbstractProjectionHandler and AbstractTaskHandler subclasses.
• FakeAuthorizationResolver<TContext> (@axion-io/core/testing) — implements AuthorizationResolver<TContext> with configurable supports result and evidence array, call recording for both supports and resolve, and reset(). The primary tool for unit-testing AbstractPolicyValidator subclasses.
• buildAuthorizationEvidence(overrides?) (@axion-io/core/testing) — constructs AuthorizationEvidence with stable defaults and per-field overrides, for use in FakeAuthorizationResolver configuration and assertion code.

Service fakes (@axion-io/core/testing)

• FakeCommandService<TInput, TResult> — implementing CommandService<TInput, TResult> with configurable result and call recording. setResult(result) switches to success mode; failWith(error) switches to rejection mode; reset() clears calls and reverts to success.
• FakeQueryService<TInput, TResult> — same API as FakeCommandService, implementing QueryService<TInput, TResult>. FakeSystemService and FakeTaskService provide the same inspection API for SystemService and TaskService dependencies.

Handler base classes (@axion-io/core)

• AbstractProjectionHandler<TPayload> — base class for projection handlers. Requires a ProjectionMaterializer, calls validateEnvelope(event) (synchronous, throws on invalid category/schema version), then delegates to project(event, materializer). Never mutates Canonical Entities or calls CommandService.
• AbstractTaskHandler<TPayload> — base class for task handlers. Requires exactly one TaskUseCase, calls validateEnvelope(task) (synchronous, throws on invalid task type/schema), then delegates to taskUseCase.execute(task) in the base class.

System and task use-case base classes (@axion-io/core)

• AbstractSystemUseCase<TInput, TResult> — base class for system-actor use cases. Requires an OperationManager and SystemService, calls validateInvariants(input) (subclass throws on invalid preconditions), creates an Operation via OperationManager using buildOperationInput(input), then delegates to executeSystem(input, operation, systemService). No PolicyValidator — system actors have authority by definition.
• AbstractTaskUseCase<TPayload, TResult> — base class for task use cases driven by TaskEnvelope. Requires a TaskService, calls validateInvariants(envelope) (throws on invalid task metadata), then delegates to executeTask(envelope, taskService). No operation creation — task use cases operate within an already-accepted operation.

Use-case orchestration base classes (@axion-io/core)

• AbstractCommandUseCase<TInput, TResult, TContext> — base class for command use cases. Requires a CommandService, calls buildCapabilityRequest(input), validates via PolicyValidator, throws AxionContractError("policy_denied") on denial, creates an Operation via OperationManager using buildOperationInput(input, request), then delegates to executeCommand(input, operation, commandService).
• AbstractQueryUseCase<TInput, TResult, TContext> — base class for query use cases. Requires a QueryService; after the same policy-validation guard, delegates to executeQuery(input, request, queryService) with no operation creation.

Service base classes (@axion-io/core)

• AbstractCommandService<TInput, TResult, TRepository, TLifecycle, TTransactionContext> — base class for concrete command-side mutation services. Requires repository, repositoryFactory, transactionRunner, outboxWriterFactory, clock, and idGenerator; accepts optional lifecycle.
• AbstractQueryService<TInput, TResult, TRepository> — base class for concrete read-only services. Accepts an optional repository. AbstractSystemService and AbstractTaskService mirror command-service transactional dependencies for system-owned and task-owned mutation services.
• AbstractProjectionMaterializer<TInput, TRepository> — base class for concrete projection-write services. Requires repository, operationManager, projectionName, and requirementId.

Lifecycle and transaction abstractions (@axion-io/core + @axion-io/core/testing)

• AbstractLifecycleStateManager<TState> — base class for entities with controlled business states. Subclasses pass an AllowedTransition<TState>[] table to the constructor and call guardTransition(from, to) before mutating; throws AxionContractError("terminal_state_transition_conflict") for non-configured transitions.
• AllowedTransition<TState> — typed { from, to } pair for declaring the lifecycle transition table.
• TransactionRunner<TContext> — port interface for CommandService transaction abstractions; injected as a constructor dependency.
• FakeTransactionRunner<TContext> (testing) — executes the transaction function immediately with a pre-configured context; inspection API: callCount, reset().