@makaio/framework 1.0.0-dev-1785407933303 → 1.0.0-dev-1786014320559

package/dist/services/automation-trigger/index.d.mts

@@ -0,0 +1,943 @@
+import { IMakaioBus } from "@makaio/framework/bus";
+import * as _$_makaio_contracts0 from "@makaio/framework/contracts";
+import { AutomationTriggerBinding, AutomationTriggerCleanup, AutomationTriggerDescriptor, AutomationTriggerListener, AutomationTriggerSubscription, AutomationTriggerType, JsonValue, MakaioNodeExtension } from "@makaio/framework/contracts";
+import { ContributionProcessor, KernelExtensionContext, KernelMakaioExtension } from "@makaio/framework/kernel";
+import { BaseService } from "@makaio/framework/service-base";
+
+//#region services/core/src/automation-trigger/automation-trigger-binding-runtime.d.ts
+/**
+ * Minimal resolution surface the binding runtime needs from a trigger registry.
+ *
+ * Declaring the dependency structurally keeps the runtime free of the registry's
+ * bus lifecycle: any owner-aware catalog that can resolve a kind to its owner and
+ * executable trigger can drive the runtime.
+ */
+interface AutomationTriggerResolver {
+  /**
+   * Resolves a trigger kind to its owning extension and executable type.
+   * @param kind - Canonical trigger kind to resolve.
+   * @returns The owner and trigger type, or `undefined` when not registered.
+   */
+  resolveRegistration(kind: string): {
+    readonly owner: string;
+    readonly type: AutomationTriggerType;
+  } | undefined;
+}
+/**
+ * Schema-validated binding admission prepared for one registration snapshot.
+ *
+ * The capability keeps parsed parameters private while exposing the canonical
+ * key a caller needs for its own handover decision. Calling {@link subscribe}
+ * consumes that exact parsed snapshot, so a transforming parameter schema can
+ * never produce one key for inspection and a different activation input.
+ */
+interface PreparedAutomationTriggerBinding {
+  /** Canonical key derived from the prepared, schema-parsed parameters. */
+  readonly bindingKey: string;
+  /** Whether this trigger's event output has an object root suitable for workflows. */
+  readonly workflowCompatible: boolean;
+  /**
+   * Attaches a listener using this prepared registration and parameter snapshot.
+   * @param listener - Listener invoked for every validated emitted event.
+   * @returns A handle whose `detach` releases this listener's reference.
+   */
+  subscribe(listener: AutomationTriggerListener): Promise<AutomationTriggerSubscription>;
+}
+/**
+ * Reference-counted activation runtime for automation trigger bindings.
+ *
+ * Four invariants define this runtime:
+ *
+ * 1. **Canonical sharing.** A binding is identified by
+ *    `<kind>:<canonical-json(parsed params)>`. Parameters are parsed through the
+ *    trigger's `paramsSchema` first and then canonicalized, so defaults and
+ *    normalizing transforms are applied before the key is computed and the
+ *    values handed to `activate` are exactly the values the key was derived
+ *    from; two bindings that mean the same thing therefore share exactly one
+ *    live activation, reference-counted by listener.
+ * 2. **Lane-serialized state, lane-free extension code.** Every internal state
+ *    transition — indexing, reference counting, retirement, abort — runs on a
+ *    single FIFO lane, so no two activations, teardowns, or replacements can
+ *    interleave their bookkeeping. Extension-owned promises (`activate` and the
+ *    cleanup it returns) and listener delivery are awaited **outside** the lane
+ *    and reconciled against the entry's map identity when they settle.
+ *    Callers keep their ordering guarantees — `detach()` still resolves only once
+ *    the cleanup has settled — while extension code can never block the lane.
+ *    That is what makes a listener free to subscribe or detach during delivery,
+ *    lets {@link close} abort an `activate` that only settles on abort, and lets
+ *    a cleanup mutate the runtime.
+ * 3. **Map identity is the single liveness signal.** Retiring an activation
+ *    unindexes it, clears its listeners, and aborts its signal — always together,
+ *    always in one lane step. An entry is therefore live exactly while it is the
+ *    indexed activation for its key: an emit from a source that outlived its
+ *    cleanup is discarded, and a late-completing activation cannot be
+ *    resurrected — its cleanup runs and nothing else. No separate disposed flag
+ *    or generation counter is needed to distinguish a superseded activation from
+ *    the live one.
+ *
+ * 4. **Registration identity gates sharing.** An activation records the
+ *    registered trigger it was built from. Sharing a live activation is only
+ *    correct while that registration is still the current one: an owner that
+ *    re-registers a kind replaces `activate`, `paramsSchema`, and `eventSchema`
+ *    wholesale, so joining the previous activation would run new subscribers
+ *    against an implementation discovery no longer advertises. A join whose
+ *    captured trigger is no longer the resolved one therefore retires the stale
+ *    activation and builds a fresh one.
+ *
+ *    Listeners on the retired activation are silenced rather than migrated. That
+ *    is the same semantic as {@link stopKind}, and for the same reason: their
+ *    consumers recover by re-subscribing on `automation-triggers.changed`, which
+ *    the replacing registration necessarily emitted before this join could be
+ *    admitted. Migrating them instead would hand them an activation whose
+ *    `activate` may still fail, with their own `subscribe` already resolved and
+ *    no error path left to report it on.
+ *
+ * The runtime deliberately does not extend `BaseService`: it owns no bus subjects
+ * and no bus lifecycle. It is a plain collaborator constructed with a resolver,
+ * so hosts can compose it into whatever lifecycle owns it and call
+ * {@link close} on teardown.
+ */
+declare class AutomationTriggerBindingRuntime {
+  private readonly resolver;
+  /** Live activations indexed by canonical binding key. */
+  private readonly bindings;
+  /** Maps issued public handles back to their internal identity. */
+  private readonly records;
+  /**
+   * The single FIFO state-transition lane.
+   *
+   * Operations placed on it must not await extension-owned promises or deliver
+   * events — that is the invariant which keeps the lane free of deadlocks.
+   */
+  private readonly lane;
+  /** Monotonic subscription id source. */
+  private subscriptionCounter;
+  /** Set by {@link close}; rejects further acquisitions. */
+  private closed;
+  /**
+   * @param resolver - Registry surface used to resolve kinds to executable
+   *   triggers and their owning extension.
+   */
+  constructor(resolver: AutomationTriggerResolver);
+  /**
+   * Attaches a listener to the binding, activating the trigger if needed.
+   *
+   * Parameters are validated through the trigger's `paramsSchema` and then
+   * checked for JSON compatibility before anything is activated, so an invalid
+   * binding never reaches extension code. When an activation already exists for
+   * the canonical key — including one that is still activating — the listener
+   * joins it and no second activation occurs, provided that activation still
+   * belongs to the current registration of the kind (invariant 4).
+   *
+   * Three phases: a lane-internal admission that installs or joins the entry, an
+   * out-of-lane await of the shared activation promise, and a lane-internal
+   * commit that issues the handle only while the admitted listener is still live.
+   *
+   * A caller that swaps one binding for another does so by subscribing the
+   * replacement and only then detaching the previous handle. That ordering is the
+   * caller's, deliberately: it keeps a shared source from being torn down and
+   * re-activated, it leaves the previous subscription fully intact when the
+   * acquisition fails, and it leaves the window between the two steps — where a
+   * caller with its own delivery bookkeeping has to settle which of the two
+   * attached listeners acts — under that caller's control.
+   * @param binding - Trigger kind plus JSON parameters to activate.
+   * @param listener - Listener invoked for every validated emitted event.
+   * @returns A handle whose `detach` releases this listener's reference.
+   * @throws When the runtime is closed, the kind is not registered, the
+   *   parameters fail validation, the activation itself fails, or a lifecycle
+   *   operation retires the admission before activation completes.
+   */
+  subscribe(binding: AutomationTriggerBinding, listener: AutomationTriggerListener): Promise<AutomationTriggerSubscription>;
+  /**
+   * Parses a binding once for both canonical-key inspection and subscription.
+   *
+   * The returned capability captures the registration that performed the parse.
+   * Its subscription rejects if that registration is replaced before admission,
+   * rather than re-parsing through a different schema under a stale key.
+   * Preparation does not activate anything and does not require the runtime to
+   * be open.
+   * @param binding - Trigger kind plus JSON parameters to prepare.
+   * @returns A prepared capability, or `undefined` when the kind is unregistered.
+   * @throws When the parameters fail the trigger's schema or are not
+   *   JSON-compatible.
+   */
+  prepareBinding(binding: AutomationTriggerBinding): PreparedAutomationTriggerBinding | undefined;
+  /**
+   * Acquires one prepared binding without parsing its parameters again.
+   * @param prepared - Private registration and parameter snapshot.
+   * @param listener - Listener to attach.
+   * @returns A detachable subscription handle.
+   */
+  private subscribePrepared;
+  /**
+   * Computes the canonical sharing key a binding would activate under.
+   *
+   * Exists so a caller that indexes its own bookkeeping by binding key — a
+   * reconciler diffing stored bindings, for instance — derives that key through
+   * the same resolution and parsing the runtime itself uses, instead of
+   * re-implementing the schema parse and canonicalization and drifting from it.
+   *
+   * Does not activate anything and does not require the runtime to be open.
+   * @param binding - Trigger kind plus JSON parameters.
+   * @returns The canonical key, or `undefined` when the kind is not registered.
+   * @throws When the parameters fail the trigger's `paramsSchema` or are not
+   *   JSON-compatible — the same rejection {@link subscribe} would produce.
+   */
+  resolveBindingKey(binding: AutomationTriggerBinding): string | undefined;
+  /**
+   * Tears down every activation contributed by one owner.
+   *
+   * Only activations whose owner was captured as `owner` at activation time are
+   * removed, so other owners keep emitting. Handles pointing at a stopped
+   * activation stay safely detachable — their `detach` becomes a no-op.
+   * @param owner - Owning extension whose activations should stop.
+   * @returns Resolves once every matching cleanup has settled.
+   */
+  stopOwner(owner: string): Promise<void>;
+  /**
+   * Tears down every activation of one trigger kind.
+   *
+   * Exists for the case where a *service an activation depends on* goes away
+   * while the trigger contributing the kind stays registered: the kind is still
+   * resolvable and still legitimately contributed, but every live activation of
+   * it is now backed by a dead collaborator. Retiring them unindexes them, which
+   * is what makes the next `subscribe` for that kind build a fresh activation
+   * against the live collaborator instead of joining a permanently inert one.
+   *
+   * Narrower than {@link stopOwner} on purpose: an owner commonly contributes
+   * several kinds with unrelated backing services, and stopping all of them would
+   * silence bindings that were never affected.
+   *
+   * The kind stays registered — this runtime holds no registrations. Handles
+   * pointing at a stopped activation stay safely detachable.
+   * @param kind - Canonical trigger kind whose activations should stop.
+   * @returns Resolves once every matching cleanup has settled.
+   */
+  stopKind(kind: string): Promise<void>;
+  /**
+   * Disposes every activation and permanently closes the runtime.
+   *
+   * Delegates to {@link close}; exists so the runtime satisfies the
+   * `ExtensionServiceLifecycle` contract from `@makaio/contracts` and the
+   * coordinator can call `service.destroy?.()` on package teardown.
+   * @returns Resolves once every cleanup has settled.
+   */
+  destroy(): Promise<void>;
+  /**
+   * Disposes every activation and permanently closes the runtime.
+   *
+   * Idempotent, and safe to call while an activation is still in flight. The
+   * lane carries only state transitions, so this call is never queued behind
+   * extension-owned code: a pending acquisition is admitted first (the lane is
+   * FIFO) and its activation is then retired here like any other. Retirement
+   * aborts the activation signal immediately, which is what lets an `activate`
+   * that only settles on abort settle at all — its cleanup then runs and this
+   * call resolves. Handles issued before close remain safely detachable.
+   * @returns Resolves once every cleanup has settled.
+   */
+  close(): Promise<void>;
+  /**
+   * Installs a new activation entry or joins an existing one. Lane-internal.
+   *
+   * Starts the single `activate` call for a new entry but never awaits it: the
+   * outcome is published on {@link ActiveBinding.activated} for the acquirer and
+   * for teardown to await after the lane is released.
+   *
+   * An existing entry is joined only when it was built from the registration this
+   * admission just resolved. Otherwise it is retired here and replaced — see
+   * {@link AutomationTriggerBindingRuntime} invariant 4.
+   * @param prepared - Once-parsed binding and registration snapshot to admit.
+   * @param listener - Listener to attach.
+   * @returns The entry joined, the allocated listener id, and any activation this
+   *   admission superseded.
+   * @throws When the runtime is closed, the kind is unknown, or its registration
+   *   changed after preparation.
+   */
+  private admitWithinLane;
+  /**
+   * Runs the single `activate` call for an entry and publishes its outcome.
+   *
+   * Deliberately not awaited by its caller: the lane must never contain
+   * extension-owned promises. `activate` is still entered synchronously, so a
+   * trigger that emits inside `activate` reaches its first listener immediately.
+   * @param entry - Entry being activated.
+   * @param type - Registered trigger providing the activation implementation.
+   * @param params - Canonical, schema-parsed activation parameters.
+   * @param deferred - Shared outcome slot every awaiter of this entry observes.
+   * @returns Resolves once the outcome has been published.
+   */
+  private startActivation;
+  /**
+   * Releases one listener reference, tearing the activation down when it was the
+   * last.
+   *
+   * A no-op when the handle was already detached, when its activation was
+   * superseded, or when the activation was removed by {@link stopOwner} or
+   * {@link close}.
+   * @param handle - Subscription handle to release.
+   * @returns Resolves once any resulting cleanup has settled.
+   * @throws When the handle was not issued by this runtime.
+   */
+  private release;
+  /**
+   * Decides the outcome of a detach and applies its state transition.
+   * Lane-internal.
+   * @param handle - Subscription handle to release.
+   * @returns The entry whose cleanup must now run, or `undefined` when the
+   *   activation survives or was already retired.
+   * @throws When the handle was not issued by this runtime.
+   */
+  private releaseWithinLane;
+  /**
+   * Retires every activation matching a predicate and awaits their cleanups.
+   *
+   * The single teardown sweep behind {@link stopOwner}, {@link stopKind}, and
+   * {@link close}. Two parts must not diverge between them: selecting entries from
+   * a snapshot while collecting only first-time retirements, and awaiting the
+   * resulting cleanups outside the lane.
+   * @param matches - Selects the activations to retire.
+   * @param beforeSweep - Optional state transition applied on the lane
+   *   immediately before the sweep, for a caller that must change runtime state
+   *   atomically with it. Must not await anything.
+   * @returns Resolves once every matching cleanup has settled.
+   */
+  private retireMatching;
+  /**
+   * Unindexes an activation, silences it, and aborts its signal. Lane-internal.
+   *
+   * Returning the entry only on the first retirement is what makes cleanup run
+   * exactly once: every teardown path decides on the lane and only the winning
+   * decision receives an entry to clean up.
+   *
+   * This is the sole remover from the index. That is what establishes invariant
+   * 3 of {@link AutomationTriggerBindingRuntime}: map identity alone answers "is
+   * this activation still live" and makes a second retirement a no-op.
+   * @param entry - Activation to retire.
+   * @returns The entry when this call retired it, `undefined` when it was
+   *   already retired.
+   */
+  private retireWithinLane;
+  /**
+   * Awaits a retired activation's cleanup. Runs outside the lane.
+   *
+   * Waits for the shared activation outcome first, so an entry retired while it
+   * was still activating is still cleaned up once `activate` settles — its
+   * signal was already aborted by the retirement, which is what lets an
+   * abort-driven activation settle at all.
+   *
+   * Cleanup failures are logged rather than propagated: teardown must stay
+   * idempotent for callers and must never abandon the remaining activations in a
+   * {@link stopOwner} or {@link close} sweep.
+   * @param entry - Retired activation to tear down.
+   * @returns Resolves once the cleanup has settled.
+   */
+  private runCleanup;
+  /**
+   * Creates a public subscription handle bound to an internal record.
+   * @param record - Internal identity of the subscription.
+   * @returns The public handle; its `detach` decides on the lane and is
+   *   idempotent.
+   */
+  private issueHandle;
+  /**
+   * Builds the activation context handed to a trigger's `activate`.
+   *
+   * The returned `emit` validates every payload against the schema captured at
+   * activation time before any listener runs, and is inert once the activation has
+   * been retired or superseded.
+   * @param entry - Activation the context belongs to.
+   * @returns The activation context for this activation only.
+   */
+  private createContext;
+  /**
+   * Validates and delivers one emitted payload to an activation's listeners.
+   *
+   * Never runs while the state-transition lane is held, so a listener is free to
+   * subscribe or detach during delivery — including for an emit made from inside
+   * `activate`.
+   * @param entry - Activation that emitted.
+   * @param payload - Raw payload supplied by the trigger.
+   * @param correlationId - Optional correlation id propagated by the source.
+   * @returns Resolves once every listener has settled.
+   * @throws When the payload fails the activation's captured `eventSchema` or is
+   *   not JSON-compatible.
+   */
+  private dispatch;
+}
+//#endregion
+//#region services/core/src/automation-trigger/automation-trigger-registry.d.ts
+/**
+ * Owner-aware registry and bus catalog for automation triggers contributed by
+ * extensions.
+ *
+ * Registration is keyed by the owning extension: every trigger kind must carry
+ * the canonical `<owner>.` prefix, kinds are globally unique across owners, and
+ * a registration batch is atomic — the complete incoming batch (including every
+ * descriptor snapshot) is validated before either index changes, so a failing
+ * batch leaves no partial registration.
+ *
+ * The registry supports dot-qualified owner names such as `makaio.clients-core`:
+ * a trigger kind must start with `<owner>.` (with a trailing dot), which
+ * permits `makaio.clients-core.profile-changed` for owner `makaio.clients-core`.
+ * Npm-scoped owners use that same exact-prefix rule: `@acme/review.review-posted`
+ * belongs to owner `@acme/review`, not a prefix-matching variant.
+ *
+ * Whole-batch replacement: each `register` call replaces that owner's entire
+ * previously registered batch atomically. An empty batch removes the owner's
+ * entries. Conflicts with another owner's kinds are rejected with an error that
+ * names both the kind and the requesting owner.
+ *
+ * Bus catalog: `onInit()` registers the `automation-triggers.list` RPC handler
+ * so callers can query the current trigger catalog without a direct reference to
+ * this service. The `automation-triggers.changed` event is emitted on every
+ * successful registration or deregistration. Registry state commits before the
+ * event is emitted, so an observer failure cannot undo a change sibling
+ * observers may already have consumed.
+ */
+declare class AutomationTriggerRegistry extends BaseService {
+  /** Registered triggers grouped by owning extension. */
+  private typesByOwner;
+  /** Global kind index for collision checks and resolution lookup. */
+  private typesByKind;
+  /**
+   * Monotonically increasing revision counter.
+   *
+   * Starts at 0 and increments on every successful `register` or `deregister`
+   * call. Included in the `automation-triggers.changed` event so subscribers
+   * can detect missed events.
+   */
+  private revision;
+  /**
+   * FIFO mutation lane.
+   *
+   * `register` and `deregister` mutate and then await notification settlement.
+   * Serializing them gives each committed change a unique revision and keeps
+   * notifications in committed revision order.
+   */
+  private readonly mutations;
+  /**
+   * Memoized {@link list} result, keyed on the kind index it was derived from.
+   *
+   * Keying on the Map identity rather than on an explicit invalidation call is
+   * what makes the memo unconditionally correct: every index mutation publishes a
+   * **new** Map, so a stale memo can never match the live index and no mutation
+   * path can forget to invalidate it.
+   */
+  private catalog;
+  /**
+   * @param bus - Bus instance used for the service lifecycle and catalog RPC.
+   */
+  constructor(bus: IMakaioBus);
+  /**
+   * Initialize the service by registering the `automation-triggers.list` RPC
+   * handler.
+   *
+   * Only discovery is exposed over the bus. Trigger activation and deactivation
+   * are in-process operations not accessible via bus subjects in this phase.
+   */
+  protected onInit(): void;
+  /**
+   * Clears all in-memory registrations on teardown so handler closure
+   * references held by the kind index are released.
+   *
+   * Assigns fresh Maps rather than clearing in place, preserving the invariant
+   * that every index mutation publishes a new Map and invalidates any memoized
+   * catalog by identity.
+   */
+  protected onDestroy(): void;
+  /**
+   * Atomically registers the complete automation trigger batch for an owner.
+   *
+   * Each call replaces that owner's previous batch entirely. The whole incoming
+   * batch — including every descriptor snapshot — is validated before either
+   * index changes, so a failing batch leaves the prior registration intact.
+   * Kinds owned by another owner still collide; an empty batch removes this
+   * owner's current registrations.
+   *
+   * Emits `automation-triggers.changed` with `reason: 'registered'` (or
+   * `'deregistered'` for an empty batch that removes a prior batch). Notification
+   * payloads identify the exact union of the previous and replacement batch's
+   * kinds. Failures are reported but do not alter the committed registry state.
+   *
+   * Serialized against every other registry mutation: validation, index
+   * replacement, and notification settlement complete before the next mutation
+   * starts.
+   *
+   * A no-op (no emit, no state change) when `definitions` is empty and the
+   * owner had no prior registrations.
+   * @param owner - The extension contributing the complete batch.
+   * @param definitions - Complete automation trigger types to register.
+   * @returns Resolves when registration commits and changed-event notification
+   * settles.
+   * @throws When a kind is not namespaced by `<owner>.`, has an empty local
+   *   name, duplicates another incoming kind, or belongs to another owner.
+   */
+  register(owner: string, definitions: readonly AutomationTriggerType[]): Promise<void>;
+  /**
+   * Applies one registration batch. Mutation-lane internal.
+   * @param owner - The extension contributing the complete batch.
+   * @param definitions - Complete automation trigger types to register.
+   * @returns Resolves when registration commits and changed-event notification
+   * settles.
+   * @throws When batch validation fails.
+   */
+  private registerWithinLane;
+  /**
+   * Deregisters all automation triggers contributed by an owner.
+   *
+   * Idempotent — a no-op (no emit) when the owner has no registered triggers.
+   * Emits `automation-triggers.changed` with `reason: 'deregistered'` on
+   * success. Notification failures are reported but do not alter the committed
+   * registry state.
+   *
+   * Serialized against every other registry mutation.
+   * @param owner - The extension to remove.
+   * @returns Resolves when deregistration commits and changed-event notification
+   * settles.
+   */
+  deregister(owner: string): Promise<void>;
+  /**
+   * Resolves a trigger kind to its owning extension and registered type
+   * snapshot.
+   *
+   * Used internally by the activation runtime to look up executable trigger
+   * fields without bus indirection. Returns `undefined` for unknown kinds so
+   * callers can gate gracefully on extension deregistration.
+   * @param kind - Canonical trigger kind to resolve, e.g. `demo.assignment`.
+   * @returns The owner and defensive type snapshot, or `undefined` when not
+   *   registered.
+   */
+  resolveRegistration(kind: string): {
+    readonly owner: string;
+    readonly type: AutomationTriggerType;
+  } | undefined;
+  /**
+   * Returns serializable descriptor snapshots for all registered automation
+   * triggers.
+   *
+   * Descriptors are detached clones deep-frozen at registration time, so the same
+   * objects are shared across calls: a caller cannot mutate the stored discovery
+   * snapshot, and the catalog RPC does not pay a deep clone of the whole catalog
+   * per query. The array itself is memoized per index revision. Descriptor
+   * derivation runs only during successful batch validation; listing never
+   * executes extension code.
+   * @returns Frozen descriptor snapshots for every registered trigger.
+   */
+  list(): readonly AutomationTriggerDescriptor[];
+  /**
+   * Validates a complete registration batch without mutating registry state.
+   *
+   * Builds defensive type snapshots and pre-computes descriptor snapshots for
+   * every trigger in the batch. If any trigger fails validation the entire
+   * batch is rejected — no partial snapshots are returned.
+   * @param owner - Owner of the proposed definitions.
+   * @param definitions - Trigger types to validate.
+   * @returns Array of registered entries with snapshotted types and descriptors.
+   * @throws When namespace, duplicate-kind, or cross-owner invariants are
+   *   violated, or when a trigger's schemas cannot be projected to JSON Schema.
+   */
+  private validateBatch;
+}
+//#endregion
+//#region services/core/src/automation-trigger/canonical-binding-key.d.ts
+/**
+ * Canonicalizes a JSON record into the exact value its binding key encodes.
+ *
+ * Defined as the parse of the canonical serialization rather than as a separate
+ * traversal, which is what makes the guarantee exact instead of merely intended:
+ * the record handed to `activate` is by construction the value
+ * {@link createCanonicalBindingKey} derived its key from, so no parameter can
+ * ever disagree with the key it produced.
+ *
+ * Two normalizations follow from that definition. Object keys come back sorted,
+ * so `activate` observes a deterministic property order. Negative zero comes back
+ * as `0`, because that is what serialization does to it — without this, a binding
+ * could hand `activate` a `-0` the key cannot express, and two parameter sets that
+ * share one activation would disagree about what that activation was given.
+ * @param record - Schema-parsed, JSON-validated binding parameters.
+ * @returns A structurally equal record in canonical form.
+ */
+declare function canonicalizeJsonRecord(record: Record<string, JsonValue>): Record<string, JsonValue>;
+/**
+ * Computes the canonical sharing key for an automation trigger binding.
+ *
+ * Two bindings share a single live activation exactly when they produce the same
+ * key. Callers must pass the **schema-parsed** parameters so that defaults and
+ * normalizing transforms are already applied — otherwise two bindings that mean
+ * the same thing would activate the underlying source twice.
+ *
+ * The key format is `<kind>:<canonical-json(params)>`. Key ordering is handled by
+ * the canonical serialization itself, so passing an already-canonicalized record
+ * yields the same key as passing the raw parsed one.
+ * @param kind - Canonical trigger kind, e.g. `demo.assignment`.
+ * @param params - Schema-parsed, JSON-validated binding parameters.
+ * @returns A stable string key identifying the shared binding.
+ */
+declare function createCanonicalBindingKey(kind: string, params: Record<string, JsonValue>): string;
+//#endregion
+//#region services/core/src/automation-trigger/packages.d.ts
+/** Token for the automation trigger registry service. */
+declare const AutomationTriggerRegistryToken: _$_makaio_contracts0.ExtensionToken<AutomationTriggerRegistry>;
+/** Token for the automation trigger binding runtime service. */
+declare const AutomationTriggerBindingRuntimeToken: _$_makaio_contracts0.ExtensionToken<AutomationTriggerBindingRuntime>;
+/** Package that starts the framework automation trigger registry. */
+declare const automationTriggerRegistryPackage: MakaioNodeExtension<IMakaioBus>;
+/**
+ * Package that starts the automation trigger binding runtime.
+ *
+ * The runtime resolves its registry lazily via a closure around
+ * `ctx.getService(AutomationTriggerRegistryToken)` rather than capturing a
+ * fixed reference at construction time. This allows the registry to restart
+ * (disable → re-enable) without forcing the runtime to restart in lock-step:
+ * the runtime service and every handle issued by it survive the gap, and
+ * contributor replay installs fresh registrations in the new registry instance
+ * before any new subscription resolves. New subscriptions therefore always
+ * resolve against the current live registry.
+ *
+ * Contributor-owned activations do not survive the gap: the contribution
+ * processor stops the sources it owns when the registry stops, because the
+ * cleanup closures that could stop them are dropped at that point. Their handles
+ * stay safely detachable — detaching a stopped activation is a no-op.
+ *
+ * Deliberately does NOT declare `dependencies: [dep(registry)]`. A non-optional
+ * dependency edge does not cascade a stop — the coordinator refuses to disable a
+ * package while active non-optional dependents remain. Declaring it would make
+ * the registry permanently undisableable whenever this runtime is active, which
+ * would remove the registry restart/replay capability the lazy resolver above
+ * exists to support. Start ordering is instead given by the position of the two
+ * packages in `frameworkCorePackages`, and the runtime needs no registry
+ * reference at construction time.
+ */
+declare const automationTriggerBindingRuntimePackage: MakaioNodeExtension<IMakaioBus>;
+//#endregion
+//#region services/core/src/automation-trigger/builtins/bus-event-trigger.d.ts
+/**
+ * Creates the built-in `makaio.bus-event` automation trigger.
+ *
+ * One activation observes exactly one subject pattern and forwards every
+ * matching **event** as a trigger event. Three properties define it:
+ *
+ * 1. **Events only.** The namespace wildcard is registered as an event handler
+ *    only, so the activation is never advertised as a request route for the whole
+ *    namespace, and a request that matches the pattern is skipped even if it ever
+ *    reaches the handler: a trigger must never observe, delay, or answer an RPC.
+ * 2. **Object-root JSON payloads.** A scalar, array, or non-JSON payload is
+ *    skipped and logged instead of thrown: the handler runs inside the emitter's
+ *    dispatch, so throwing would surface a trigger's validation problem as a
+ *    failure of the unrelated code that emitted the event.
+ * 3. **No consumer semantics.** No workflow identity and no consumer-owned
+ *    filtering live here. Filtering an already-emitted event is the
+ *    subscriber's concern; this trigger only decides what an activation
+ *    observes.
+ *
+ * The bus is captured here, at trigger-creation time, from the contributing
+ * extension's context — not from the activation context — so every activation
+ * of this trigger observes the same bus the extension was activated with.
+ * @param bus - Bus instance owned by the contributing extension.
+ * @returns The registry-boundary trigger type for `makaio.bus-event`.
+ */
+declare function createBusEventAutomationTrigger(bus: IMakaioBus): AutomationTriggerType;
+/**
+ * Every built-in automation trigger that needs nothing but a bus.
+ *
+ * The composition seam for hosts that assemble their own trigger batch: a worker
+ * or a headless host that must observe bus events, but composes no cron scheduler,
+ * gets the bus-backed set from here instead of listing individual factories and
+ * silently falling behind when another bus-backed built-in is added. The
+ * framework's own built-ins package composes this list plus the triggers that need
+ * more than a bus.
+ * @param bus - Bus instance the activations observe.
+ * @returns The bus-backed built-in trigger types.
+ */
+declare function busBackedAutomationTriggers(bus: IMakaioBus): readonly AutomationTriggerType[];
+//#endregion
+//#region services/core/src/automation-trigger/cron-scheduler.d.ts
+/**
+ * One schedule request placed by an active cron automation trigger binding.
+ *
+ * Carries no workflow identity and no machine role: who reacts to a firing, and
+ * whether this host is allowed to schedule at all, are decided above this port.
+ * A provider only needs to know when to fire and how to report a firing.
+ */
+interface AutomationCronScheduleInput {
+  /**
+   * Canonical binding key of the requesting activation.
+   *
+   * Diagnostic identity, supplied by the trigger so a provider can attribute a
+   * schedule to the binding that owns it. Providers must not treat it as a
+   * unique index: the binding runtime may briefly hold a retiring and a fresh
+   * activation of the same key at the same time.
+   */
+  readonly bindingKey: string;
+  /** Cron expression, e.g. `0 9 * * 1`. */
+  readonly schedule: string;
+  /** IANA timezone the expression is evaluated in. */
+  readonly timezone: string;
+  /**
+   * Reports one firing to the requesting activation.
+   * @param payload - The scheduled occurrence that fired.
+   * @returns Resolves once the firing has been dispatched.
+   */
+  readonly emit: (payload: {
+    readonly scheduledFor: number;
+  }) => Promise<void>;
+}
+/**
+ * Host-selected provider that turns cron schedules into firings.
+ *
+ * The framework ships a local, in-process provider; a host that must schedule
+ * centrally (for example through a relay) registers its own provider under
+ * {@link AutomationCronSchedulerToken} instead. Exactly one provider is active
+ * in a booted runtime.
+ */
+interface AutomationCronScheduler {
+  /**
+   * Registers one cron schedule.
+   * @param input - Schedule expression, timezone, owner key, and firing sink.
+   * @returns Cleanup that cancels this schedule; idempotent.
+   * @throws When the schedule expression or timezone is not valid.
+   */
+  readonly schedule: (input: AutomationCronScheduleInput) => Promise<AutomationTriggerCleanup>;
+}
+/** Token for the host-selected automation cron scheduler provider. */
+declare const AutomationCronSchedulerToken: _$_makaio_contracts0.ExtensionToken<AutomationCronScheduler>;
+/**
+ * Rejects a schedule request whose expression or timezone cannot be evaluated.
+ *
+ * Lives beside the port rather than inside one provider because every provider
+ * owes callers the same rejection: a provider that accepts an unparseable
+ * expression — because it forwards scheduling elsewhere and only finds out later —
+ * would report a healthy binding that silently never fires, and the binding's
+ * author would learn about it from nothing. Validating against the same cron
+ * implementation the local provider runs is what makes "accepted here" mean
+ * "schedulable there".
+ *
+ * Constructs and immediately discards a paused job: croner performs its parse in
+ * the constructor, and a paused instance starts no timer, so nothing is scheduled.
+ *
+ * `nextRun()` is called for its validation rather than its value. Croner accepts
+ * an unknown timezone at construction and only rejects it when an occurrence is
+ * actually resolved, so without this call an unresolvable timezone would pass
+ * validation and instead surface later — as a raw croner error from whichever
+ * provider first tried to use it, naming neither the timezone nor the binding.
+ * @param input - Schedule request whose expression and timezone are checked.
+ * @throws When croner rejects the expression or the timezone, with the offending
+ *   values and the requesting binding named.
+ */
+declare function assertValidCronSchedule(input: AutomationCronScheduleInput): void;
+//#endregion
+//#region services/core/src/automation-trigger/builtins/cron-trigger.d.ts
+/**
+ * Creates the built-in `makaio.cron` automation trigger.
+ *
+ * The trigger owns no timers. It resolves the host-selected
+ * {@link AutomationCronScheduler} and delegates, so the same binding semantics
+ * hold whether a host schedules in-process or centrally.
+ *
+ * The binding key handed to the scheduler is the one the runtime supplies on the
+ * activation context, so a provider attributing a job to a binding names exactly
+ * what the runtime indexed it under.
+ *
+ * The scheduler is resolved through the supplied resolver at activation time
+ * rather than captured at creation time, so a provider that restarts is picked
+ * up by the next activation instead of leaving this trigger holding a dead
+ * reference.
+ * @param resolveScheduler - Resolves the currently registered provider.
+ * @returns The registry-boundary trigger type for `makaio.cron`.
+ */
+declare function createCronAutomationTrigger(resolveScheduler: () => AutomationCronScheduler | undefined): AutomationTriggerType;
+//#endregion
+//#region services/core/src/automation-trigger/cron-scheduler-selection.d.ts
+/** Minimal package view needed to detect an already-present provider. */
+interface CronSchedulerProviderView {
+  /** Package name; a provider registers under the scheduler token name. */
+  readonly name: string;
+  /** Human-readable name used in duplicate-provider diagnostics. */
+  readonly displayName?: string;
+}
+/** Inputs of one host's cron scheduler provider decision. */
+interface AutomationCronSchedulerSelection {
+  /**
+   * Provider packages explicitly contributed by host composition seams, if any.
+   *
+   * Must register under {@link AutomationCronSchedulerToken}; a package that
+   * does not is a wiring mistake and fails boot rather than silently leaving the
+   * runtime without a scheduler.
+   *
+   * More than one entry is a composition error. The array form lets boot combine
+   * its direct host option with descriptor server-module host exports before
+   * making one deterministic provider decision.
+   */
+  readonly hostPackages?: readonly MakaioNodeExtension<IMakaioBus>[] | undefined;
+  /**
+   * Every package the host is about to load, framework and extension alike.
+   *
+   * Scanned for provider registrations so a second provider is rejected before
+   * the coordinator starts either of them.
+   */
+  readonly loadedPackages: readonly CronSchedulerProviderView[];
+}
+/**
+ * Decides which cron scheduler provider package a host must add.
+ *
+ * Exactly one provider is active in a booted runtime:
+ *
+ * - A host that supplies one provider package uses it, and no loaded package may also
+ *   register the service.
+ * - A host that supplies none uses the loaded provider when there is exactly
+ *   one, and otherwise falls back to the framework's local provider — that
+ *   fallback is what makes framework-only boot work with no host wiring.
+ * - Two providers, or a host package that does not register the service, fail
+ *   boot with a message naming the offenders.
+ * @param selection - The host's explicit choice plus the packages being loaded.
+ * @returns The provider package to add, or `undefined` when a loaded package
+ *   already provides one.
+ * @throws When a host package does not register the scheduler service, or when
+ *   more than one provider would be active.
+ */
+declare function selectAutomationCronSchedulerPackage(selection: AutomationCronSchedulerSelection): MakaioNodeExtension<IMakaioBus> | undefined;
+//#endregion
+//#region services/core/src/automation-trigger/local-cron-scheduler.d.ts
+/**
+ * In-process {@link AutomationCronScheduler} backed by croner.
+ *
+ * The default provider for hosts that schedule locally. It owns nothing but its
+ * jobs: no workflow lookup, no persistence, no machine-role decision. A host
+ * that must not schedule locally simply registers a different provider under
+ * {@link AutomationCronSchedulerToken}.
+ *
+ * Jobs are held in a set of entries rather than a map keyed by binding key,
+ * because two activations of the same key can legitimately overlap while one is
+ * retiring. Each cleanup cancels exactly the job it created, so an overlapping
+ * pair can never cancel each other's job or leak one past {@link shutdown}.
+ */
+declare class LocalAutomationCronScheduler implements AutomationCronScheduler {
+  /** Live jobs; entry identity is what a cleanup cancels. */
+  private readonly jobs;
+  /**
+   * Registers one cron schedule.
+   *
+   * The schedule is validated, then the croner instance is constructed, before
+   * the entry is tracked — so an invalid expression or timezone rejects without
+   * leaving a job behind. A failing `emit` is logged rather than propagated: it
+   * runs inside croner's timer callback, where an escaping rejection would become
+   * an unhandled one and could stop the job from firing again.
+   * @param input - Schedule expression, timezone, owner key, and firing sink.
+   * @returns Cleanup that cancels exactly this schedule; idempotent.
+   * @throws When croner rejects the expression or the timezone.
+   */
+  schedule(input: AutomationCronScheduleInput): Promise<AutomationTriggerCleanup>;
+  /**
+   * Cancels every live schedule.
+   *
+   * Idempotent, and the only teardown path a host needs: the scheduler holds no
+   * other resources.
+   */
+  shutdown(): Promise<void>;
+  /**
+   * Cancels every live schedule on service teardown.
+   *
+   * Delegates to {@link shutdown}; exists so the scheduler satisfies the
+   * `ExtensionServiceLifecycle` contract and the coordinator can call
+   * `service.destroy?.()` on package teardown.
+   * @returns Resolves once every job has been cancelled.
+   */
+  destroy(): Promise<void>;
+  /**
+   * Number of live schedules.
+   * @returns Count of jobs currently registered.
+   */
+  activeScheduleCount(): number;
+  /**
+   * Builds the croner job for one schedule request.
+   *
+   * `scheduledFor` is the **scheduled occurrence**, not the moment the callback
+   * ran. Croner's `currentRun()` is the wall clock captured when it entered the
+   * callback, so a busy event loop would report a drifted minute and every
+   * consumer of the payload would inherit that drift. The occurrence is therefore
+   * tracked here: seeded from the job's next run before it can fire, and rolled
+   * forward inside the callback, where `nextRun()` already reports the occurrence
+   * after the one being served.
+   *
+   * Infallible by precondition: the caller already ran
+   * {@link assertValidCronSchedule} against the same expression and timezone, so
+   * the construction below cannot reject them.
+   * @param input - The schedule request being registered.
+   * @returns A started croner instance.
+   */
+  private createJob;
+}
+/**
+ * Package registering the in-process cron scheduler provider.
+ *
+ * The default choice for framework-only boots. A host replaces it by supplying
+ * its own provider package for {@link AutomationCronSchedulerToken}; exactly one
+ * provider may be registered in a booted runtime.
+ */
+declare const localAutomationCronSchedulerPackage: MakaioNodeExtension<IMakaioBus>;
+//#endregion
+//#region services/core/src/automation-trigger/builtins/package.d.ts
+/**
+ * Owner name of the framework's built-in automation triggers.
+ *
+ * Deliberately the bare `makaio` namespace: the registry requires every trigger
+ * kind to be prefixed with its owner, and the built-in kinds are canonically
+ * `makaio.bus-event` and `makaio.cron`. Registering them under the same `makaio`
+ * owner keeps the owner/kind invariant in force for built-ins instead of
+ * carving out an exception for them.
+ */
+declare const AUTOMATION_TRIGGER_BUILTINS_OWNER = "makaio";
+/**
+ * Package contributing the framework's built-in automation triggers.
+ *
+ * Contributes through the ordinary `automationTriggers` surface, so built-ins
+ * take exactly the same registration, replay, and teardown path as any
+ * extension-contributed trigger. Each trigger captures what it needs from the
+ * contribution context at creation time — the bus for `makaio.bus-event`, a lazy
+ * scheduler resolver for `makaio.cron` — so the activation context stays free of
+ * host wiring.
+ *
+ * The dependency on the cron scheduler provider is declared **optional**, which
+ * buys start ordering without a disable refusal: a provider present in the
+ * composition is started before these built-ins, so the first reconciliation that
+ * activates a stored `makaio.cron` binding already finds it — a host that lists
+ * its provider after this package would otherwise leave those bindings
+ * unavailable with no further signal to retry on. When no provider is composed at
+ * all the built-ins still register, and a `makaio.cron` activation then fails with
+ * a message naming the missing service, which keeps `makaio.bus-event` available
+ * to a host whose scheduler is degraded.
+ */
+declare const automationTriggerBuiltinsPackage: MakaioNodeExtension<IMakaioBus>;
+//#endregion
+//#region services/core/src/automation-trigger/automation-trigger-contribution-processor.d.ts
+/** Runtime hooks used to replay contributions after registry/runtime activation. */
+interface AutomationTriggerContributionProcessorOptions {
+  /**
+   * Enumerate active extensions in dependency order.
+   *
+   * The registry and the binding runtime can both be enabled after an extension
+   * contributing automation triggers is already active, so those active
+   * contributors are replayed after either one starts.
+   * @param callback - Called for each active extension and its context.
+   */
+  readonly forEachActiveExtension: (callback: (name: string, pkg: KernelMakaioExtension, ctx: KernelExtensionContext) => void) => void;
+}
+/**
+ * Processes AutomationTrigger contributions from extensions.
+ *
+ * Calls each extension's `automationTriggers.createAutomationTriggers(ctx)`
+ * factory during activation and registers the returned definitions with the
+ * `AutomationTriggerRegistry` under the extension name; deregisters them and
+ * tears down their active bindings via
+ * {@link AutomationTriggerBindingRuntime.stopOwner} when the extension stops.
+ *
+ * Contributor activation is atomic: if `createAutomationTriggers` or the
+ * registry replacement throws, the existing registration and its cleanup remain
+ * intact. Ownership bookkeeping across restarts lives in
+ * {@link AutomationTriggerContributionOwnership}.
+ * @param options - Runtime hooks used for late registry-owner activation.
+ * @returns Contribution processor that manages AutomationTrigger registration.
+ */
+declare function createAutomationTriggerContributionProcessor(options: AutomationTriggerContributionProcessorOptions): ContributionProcessor;
+//#endregion
+export { AUTOMATION_TRIGGER_BUILTINS_OWNER, type AutomationCronScheduleInput, type AutomationCronScheduler, type AutomationCronSchedulerSelection, AutomationCronSchedulerToken, AutomationTriggerBindingRuntime, AutomationTriggerBindingRuntimeToken, type AutomationTriggerContributionProcessorOptions, AutomationTriggerRegistry, AutomationTriggerRegistryToken, type AutomationTriggerResolver, LocalAutomationCronScheduler, type PreparedAutomationTriggerBinding, assertValidCronSchedule, automationTriggerBindingRuntimePackage, automationTriggerBuiltinsPackage, automationTriggerRegistryPackage, busBackedAutomationTriggers, canonicalizeJsonRecord, createAutomationTriggerContributionProcessor, createBusEventAutomationTrigger, createCanonicalBindingKey, createCronAutomationTrigger, localAutomationCronSchedulerPackage, selectAutomationCronSchedulerPackage };