`eventsSchema`

Purpose

Event-bus topology declaration. Lists the subjects this plugin publishes and the subjects it subscribes to. Subjects follow the domain.entity.verb convention which the regex enforces — the host's bus cross-checks publish/subscribe pairs at boot for typo + drift surfacing.

Features

Topic regex enforces lower-snake_case dotted segments, ≥2 segments
Optional publishes / subscribes readonly string arrays
Empty event blocks are allowed (a plugin may neither publish nor subscribe)
Cross-plugin pairing surface for the host's bus introspector

Basic Example

import { eventsSchema } from "@suaveplan/api-manifest/schema";
eventsSchema.parse({ publishes: ["billing.invoice.created"] });

Advanced Example

import { eventsSchema } from "@suaveplan/api-manifest/schema";
const events = eventsSchema.parse({
  publishes: ["billing.invoice.created", "billing.payment.succeeded"],
  subscribes: ["users.user.deleted"],
});

API Reference

eventsSchema: z.ZodObject<{ publishes?, subscribes? }>
Events = z.infer<typeof eventsSchema>

Implementation Notes

The topic regex (^[a-z][a-z0-9_-]*(\.[a-z][a-z0-9_-]*)+$) enforces at least one dot — single-segment topics are reserved for the bus's internal channels. Lower-case letters, digits, hyphens, and underscores are accepted inside segments; mixed-case is rejected to match the rest of the bus contract. Cross-plugin checking (does anything subscribe to what we publish?) lives in the host, not in this schema.

Cross-package Notes

This module is part of the @suaveplan/api-manifest Stage-1 contract package. It sits beneath every Stage-2 consumer (api-host, api-loader, the admin CLI, the IDE plugin) and above the foundation packages (@suaveplan/error, @suaveplan/types). The strict-mode top-level rejection of unknown keys means upgrading from manifest v1 to v2 is an OpenSpec-driven event: a new key landing in a consumer manifest is a parse failure rather than a silent drift, which is exactly the contract this stage exists to guarantee.

When the host reloads a plugin without a full restart, every manifest field this module validates is compared against the install-time manifestHash. A mismatch triggers a hard rollback via the RollbackJournal because the host's invariants (route mounts, registered capabilities, declared scopes) are derived from these exact bytes. Treat the schemas and validators here as the contract surface, not just an input filter — downstream code reads manifest.foo.bar and relies on those keys being present, well-typed, and non-undefined in the documented optionality regions.

2.6 KiB Raw Blame History

eventsSchema