@sema-agent/mods-kernel

The mods kernel of the sema engine: one extension bus — registration and its two seats, tiers, admission through plugin.register, the ($, e, next) chain with next.to, re-entry frames, site rules, the failure / abort columns, .catch and the self budget. It is compiled from the same source the engine embeds, so a shell or a client can run the same rules on its own bus. Zero dependencies; runs in Node and in browsers; ships its own types.

Install

npm install @sema-agent/mods-kernel

ES modules only ("type": "module"), Node >= 20.18.1 where Node is used. One entry, .; there are no deep paths.

Version

@sema-agent/[email protected] is cut with @sema-agent/[email protected]: the same version number, built from the same commit. A package version moves with every core release whether or not the kernel changed; it says which core it was cut with, not whether the contract moved.

Two copies: KERNEL_CONTRACT_VERSION

Two copies of the kernel interoperate on plain objects (no instanceof, no module identity). A host that loads one copy beside another compares KERNEL_CONTRACT_VERSION for equality. Nothing in the kernel or the engine reads it, so two copies that differ are told apart only by a host that compares them. The number is an integer independent of the package version; it moves only when the chain semantics, the registration form, the event closed set (names and side) or the failure columns (failure, abort, pinned keys, an event's own budget ceiling, whether $ may call it) change — once per release, however many of them change in it.

@sema-agent/core does not depend on this package: it compiles the same source into its own build, so a process that installs both holds two copies. This package is for a host that runs its own bus; the engine does not need it installed.

Which side raises an event

Every name in MOD_EVENT_TABLE carries a side — engine, surface or both, the closed set MOD_EVENT_SIDES — and that is the one place the answer lives: readOnSide(name, side) and stationOn(name, side) read the same row.

import { KERNEL_CONTRACT_VERSION, MOD_EVENT_SIDES, MOD_EVENT_TABLE, readOnSide } from "@sema-agent/mods-kernel";

console.log(KERNEL_CONTRACT_VERSION);                  // an integer
console.log(MOD_EVENT_SIDES);                          // [ 'engine', 'surface', 'both' ]
console.log(MOD_EVENT_TABLE["tool.check"].side);       // engine
console.log(MOD_EVENT_TABLE["ui.render"].side);        // surface
console.log(readOnSide("plugin.register", "surface")); // true: its side is both

Exports

Each name below is a runtime value or a type exported from the package root. The root's declarations are the contract; a removed or re-kinded export is named as breaking in the @sema-agent/core release notes.

| Group | Names | | --- | --- | | Contract and closed sets | KERNEL_CONTRACT_VERSION MOD_TIERS MOD_SEATS MOD_EVENT_SIDES MOD_FAILURE_ANSWERS MOD_ABORT_POSTURES NEXT_TO_TABLE SEAT_TIER_TABLE | | Event table and readers | MOD_EVENT_TABLE isModEventName expandModPattern expandOnSide stationOn readOnSide failureRefuses nextToRefusal | | Event table types | ModTier ModRegistrationTier ModSeat ModEventSide ModBusSide ModFailureAnswer ModAbortPosture ModStation ModEventRow ModEventName | | Budgets | DEFAULT_MOD_BUDGET_MS CATCH_BUDGET_MS RUNAWAY_AFTER_MS POST_ABORT_GRACE_MS MAX_TIMER_MS clockMsRefusal resolveModBudgetMs ModBudgetReading | | Failure causes and site rules | MOD_FAILURE_CAUSES ModFailureCause ModEventPayload ModAnswerCheck ModAnswerRanks ModDispatchRun ModAnswerer ModMatcher ModSkip | | Registration | ENGINE_ORIGIN MODS_INVALID_CODE MODS_REGISTRATION_REFUSED_CODE MOD_TRACE_OUTCOMES ModTraceOutcome ModUses ModOrigin ModPluginFacts ModDollarBase ModTraceEntry ModCaughtError ModNext ModHandler ModHandlerOptions On ModRegistration ModAdmissionRecord ModSeats | | Typed event maps | ModEventPair ModEventMap ModTypedNext ModTypedHandler MappedOn | | Admission and the bus | admitMods ModFrame ModBottomContext ModMethodBottom ModMethodSeat ModMethodBottoms ModCallEntry ModCallEntries ModDispatchOutcome ModDispatchOptions ModParticipant ModBus ModMountedHandler ModBusInput ModTimer |

License

Business Source License 1.1, the same terms as @sema-agent/core; the licence text is the LICENSE file in this package.