@phis/contracts 0.7.3 → 0.7.4

package/README.md

@@ -61,7 +61,14 @@ erased at compile time apart from a handful of constants.
 What it covers:
 
 - **Manifest** -- `PhisAddonManifestV1`: identity, version, required Core capabilities, the routes an
-  Add-on claims, the services it provides.
+  Add-on claims, the services it provides, the jobs it runs and the events it listens to or emits.
+- **Jobs and events** -- a job carries a `PhisAddonJobSchedule` (`every` one of
+  `PHIS_ADDON_JOB_INTERVALS`, five minutes at the shortest, with `at` and `weekday` for the daily and
+  weekly steps) that Core keeps: each moment of a schedule is run by exactly one instance. An event an
+  Add-on emits is a `PhisAddonEmittedEventId`, its own id in front (`@scope/name:what.happened`),
+  declared under `emits` and sent through the `events` capability (`PhisEventsCapabilityV1`); a listener
+  receives a `PhisAddonEmittedEventSubject` with emitter, time, hop count, dedupe key and facts. Core's
+  own events keep their bare names. `PHIS_ADDON_EVENT_MAX_HOPS` bounds a chain of handlers emitting.
 - **Runtime** -- `PhisAddonRuntimeV1`, `PhisAddonHandler`, `PhisAddonRequestContext`. The artifact
   exports it under the name `phisAddon` (`PhisAddonRuntimeModuleV1`).
 - **Schema** -- `PhisAddonSchemaDescriptor` and its column, index and constraint descriptors. Tables are

package/dist/addon.d.ts

@@ -12,7 +12,7 @@
  * back a constant, it is in the wrong package.
  */
 import type { PhisAddonCapabilities, PhisAddonEventHandler, PhisAddonJobHandler, PhisSiteAccess } from "./capabilities.js";
-import type { PhisAddonEventId, PhisCoreCapabilityId, PhisServiceKind } from "./core.js";
+import type { PhisAddonEmittedEventId, PhisAddonEventId, PhisCoreCapabilityId, PhisServiceKind } from "./core.js";
 import type { PhisAddonQueryCatalog } from "./queries.js";
 import type { PhisAddonSchemaDescriptor } from "./schema.js";
 export declare const PHIS_ADDON_MANIFEST_VERSION: 1;
@@ -101,17 +101,61 @@ export type PhisAddonServiceProviderDescriptor = {
     factoryExport: string;
     requiredCoreCapabilities: PhisCoreCapabilityId[];
 };
+/**
+ * The steps a job may run at. Every step divides the hour or the day, so the moments a schedule names
+ * fall on the clock -- `5m` is :00, :05, :10 -- and every instance of Core computes the same moment
+ * from the same clock without asking another.
+ *
+ * Nothing shorter than five minutes: a job that has to look more often than that is polling for an
+ * event, and an event is what it should be given. Jobs run per Site, so a short step multiplies by
+ * the Sites of a stage, and the services a job reads from have quotas of their own.
+ */
+export declare const PHIS_ADDON_JOB_INTERVALS: readonly ["5m", "15m", "30m", "hourly", "daily", "weekly"];
+export type PhisAddonJobInterval = (typeof PHIS_ADDON_JOB_INTERVALS)[number];
+/**
+ * When a job wants to run. Core keeps it: the schedule is a promise, not a note for the operator.
+ *
+ * A schedule is a series of moments, and each moment is claimed by exactly one instance of Core --
+ * the claim is a row whose key is the moment, so the database, not a leader, decides who runs. A
+ * moment nobody claimed while every instance was down is run once at the next start, the latest one
+ * only; a job does not receive a week of missed runs after a week of downtime. A job still running
+ * when its next moment comes has that moment recorded as skipped rather than run beside itself, which
+ * is why a handler must finish well inside its own step.
+ */
+export type PhisAddonJobSchedule = {
+    every: PhisAddonJobInterval;
+    /**
+     * The time of day, `HH:MM` in UTC, for `daily` and `weekly`; absent means `00:00`. Not for the shorter
+     * steps, which fall on the clock by themselves.
+     */
+    at?: string;
+    /** The ISO weekday for `weekly`, 1 (Monday) to 7 (Sunday); absent means Monday. */
+    weekday?: number;
+};
 export type PhisAddonJobDescriptor = {
     id: string;
     handler: string;
     /**
-     * How often this job expects to run, for the operator to read -- never a schedule Core keeps.
+     * When Core runs this job. Absent means it runs only when an operator starts it with `phis addon
+     * job`, which also runs a scheduled job out of turn.
      *
-     * phi-server serves from several instances, so an in-process timer would fire once per instance for
-     * one intended run. The operator schedules `phis addon job run`, which is one runner by construction,
-     * and this field tells them what the Add-on had in mind.
+     * Optional like every field added after this manifest version was in the wild.
      */
-    suggestedInterval?: "hourly" | "daily" | "weekly";
+    schedule?: PhisAddonJobSchedule;
+};
+/**
+ * One event this Add-on announces under its own name.
+ *
+ * Declared like a job or a route: the id, its emitter's own id in front, is part of the manifest and
+ * therefore of the digest, so what an installed Add-on can say to the others is readable at install.
+ * Emitting an undeclared event is refused. `audience` says who may listen: every Add-on of the Site
+ * that declares a handler for it, which is the default, because the operator installed each of them;
+ * or `self`, for an Add-on that uses the outbox to hand work to its own handler after the fact.
+ */
+export type PhisAddonEmittedEventDescriptor = {
+    id: PhisAddonEmittedEventId;
+    description?: string;
+    audience?: "stage" | "self";
 };
 /**
  * One setting an operator may configure for this Add-on.
@@ -259,6 +303,13 @@ export type PhisAddonManifestV1 = {
      * Add-on that declares them and links nothing is told nothing.
      */
     eventHandlers?: PhisAddonEventHandlerDescriptor[];
+    /**
+     * The events this Add-on emits. Absent means none, and an emit of anything is refused.
+     *
+     * Optional like `eventHandlers`. Declaring an event is not delivering it: a row is written only for
+     * an Add-on of the Site that declares a handler for the id, and none at all where nobody listens.
+     */
+    emits?: PhisAddonEmittedEventDescriptor[];
     /**
      * What an operator may configure. Absent means nothing is.
      *

package/dist/addon.js

@@ -13,3 +13,13 @@
  */
 export const PHIS_ADDON_MANIFEST_VERSION = 1;
 export const PHIS_ADDON_ABI_VERSION = 1;
+/**
+ * The steps a job may run at. Every step divides the hour or the day, so the moments a schedule names
+ * fall on the clock -- `5m` is :00, :05, :10 -- and every instance of Core computes the same moment
+ * from the same clock without asking another.
+ *
+ * Nothing shorter than five minutes: a job that has to look more often than that is polling for an
+ * event, and an event is what it should be given. Jobs run per Site, so a short step multiplies by
+ * the Sites of a stage, and the services a job reads from have quotas of their own.
+ */
+export const PHIS_ADDON_JOB_INTERVALS = ["5m", "15m", "30m", "hourly", "daily", "weekly"];

package/dist/capabilities.d.ts

@@ -12,7 +12,7 @@
  * at the point where it made the mistake.
  */
 import type { PhisAssetsCapabilityV1 } from "./assets.js";
-import type { PhisAddonThreadEventId } from "./core.js";
+import type { PhisAddonEmittedEventId, PhisAddonThreadEventId } from "./core.js";
 import type { PhisPaymentChangedEventFacts, PhisPaymentNotificationsCapabilityV1, PhisPaymentsCapabilityV1 } from "./payments.js";
 import type { PhisDataCapabilityV1 } from "./queries.js";
 import type { PhisResourceLinksCapabilityV1 } from "./resource-links.js";
@@ -109,6 +109,52 @@ export type PhisAddonCapabilities = {
     paymentNotifications?: PhisPaymentNotificationsCapabilityV1;
     /** Writing to a person about an occasion this Add-on declared; Core owns the frame and the sending. */
     notifications?: PhisNotificationsCapabilityV1;
+    /** Announcing an event this Add-on declared under its own name; Core owns the outbox and the delivery. */
+    events?: PhisEventsCapabilityV1;
+};
+/**
+ * The events capability: `@phis/server/events:v1`.
+ *
+ * An Add-on says that something happened; Core writes one outbox row per Add-on of this Site that
+ * declares a handler for the event, and delivers them the way it delivers its own events -- after the
+ * fact, in order, retried until they arrive. Emitting is only a write to the outbox, so it is cheap and
+ * never waits for a listener.
+ *
+ * `facts` are values about what happened, as JSON, bounded in size, and never references into another
+ * Add-on's tables: a listener runs with authority over its own tables only, and a fact it cannot read
+ * is a fact it should have been handed. `dedupeKey` makes a repeated emit safe -- a second call with
+ * the same key writes nothing for a listener already owed the first.
+ *
+ * Refused: an event the manifest does not declare under `emits`, a call from an unverified hook, and
+ * an emit from a handler already at `PHIS_ADDON_EVENT_MAX_HOPS`. Answers how many listeners were
+ * written for; zero means nobody on this Site listens, which is not a failure.
+ */
+export type PhisEventsCapabilityV1 = {
+    emit(input: PhisAddonEmitEventInput): Promise<{
+        recipients: number;
+    }>;
+};
+export type PhisAddonEmitEventInput = {
+    event: PhisAddonEmittedEventId;
+    facts?: Readonly<Record<string, unknown>>;
+    /** Unique within the Site and the event; a second emit with the same key writes nothing new. */
+    dedupeKey?: string;
+};
+/**
+ * What a listener is handed about an event another Add-on -- or the same one -- emitted.
+ *
+ * The emitter's id says who, `occurredAt` when (the moment the outbox row was written), `hop` how many
+ * handlers the chain has passed through so far, and `facts` what the emitter said. `dedupeKey` is the
+ * emitter's, where it gave one; the delivery's own key, stable across retries, is `deliveryId` on the
+ * context, as for every event.
+ */
+export type PhisAddonEmittedEventSubject = {
+    kind: "emitted";
+    emitter: string;
+    occurredAt: string;
+    hop: number;
+    dedupeKey: string | null;
+    facts: Readonly<Record<string, unknown>>;
 };
 /**
  * The roles capability: `@phis/server/roles:v1`.
@@ -399,8 +445,9 @@ export type PhisSettingsCapabilityV1 = {
  *
  * No request, no headers, and above all no actor: a job is the Add-on acting on its own data, not a
  * person acting through it. That is why the row-level ladder does not apply inside one, and why a job
- * is reachable only from `phis addon job run` and never from a route -- an Add-on that could start its
- * own job from a request would have built itself a way around the ladder.
+ * is started only by Core's scheduler at the moments its `schedule` names, or by an operator with
+ * `phis addon job`, and never from a route -- an Add-on that could start its own job from a request
+ * would have built itself a way around the ladder.
  */
 export type PhisAddonJobContext = {
     addonId: string;
@@ -434,7 +481,10 @@ export type PhisAddonEventFacts = {
         threadId: number;
         messageId: number | null;
     };
-} | PhisPaymentChangedEventFacts;
+} | PhisPaymentChangedEventFacts | {
+    event: PhisAddonEmittedEventId;
+    subject: PhisAddonEmittedEventSubject;
+};
 export type PhisAddonEventContext = PhisAddonEventFacts & {
     addonId: string;
     /** This delivery, stable across retries, so a handler can recognise one it already settled. */

package/dist/core.d.ts

@@ -50,6 +50,8 @@ export declare const PHIS_CORE_CAPABILITIES: {
     readonly paymentNotifications: "@phis/server/payment-notifications:v1";
     /** Writing to a person about an occasion the Add-on declared, with Core owning frame and transport. */
     readonly notifications: "@phis/server/notifications:v1";
+    /** Announcing an event this Add-on declared under its own name, for the Add-ons of this Site that listen. */
+    readonly events: "@phis/server/events:v1";
 };
 export type PhisCoreCapabilityId = (typeof PHIS_CORE_CAPABILITIES)[keyof typeof PHIS_CORE_CAPABILITIES];
 /**
@@ -75,8 +77,27 @@ export declare const PHIS_ADDON_EVENTS: {
     readonly paymentChanged: "payment.changed";
 };
 export type PhisAddonThreadEventId = Exclude<(typeof PHIS_ADDON_EVENTS)[keyof typeof PHIS_ADDON_EVENTS], "payment.changed">;
-/** Delivered v1 event vocabulary, discriminated by its owned subject. */
-export type PhisAddonEventId = PhisAddonThreadEventId | PhisPaymentChangedEventFacts["event"];
+/** The events Core itself emits: the thread events and the Payment event. */
+export type PhisCoreEventId = PhisAddonThreadEventId | PhisPaymentChangedEventFacts["event"];
+/**
+ * An event an Add-on emits, named under the Add-on that emits it: `@scope/name:what.happened`.
+ *
+ * The emitter's own id is the first half, so two Add-ons cannot name the same event and a reader of
+ * a manifest sees who announces it without looking anything up. The second half is the Add-on's own
+ * word for it, `^[a-z][a-z0-9.-]*$`, the shape Core's own event names have. Core's names stay bare:
+ * a bare name is Core's, a prefixed one is an Add-on's, and the two can never be confused.
+ */
+export type PhisAddonEmittedEventId = `@${string}/${string}:${string}`;
+/** Delivered v1 event vocabulary: Core's own events, and what an installed Add-on emits. */
+export type PhisAddonEventId = PhisCoreEventId | PhisAddonEmittedEventId;
+/**
+ * How many Add-ons an event may pass through.
+ *
+ * An Add-on that emits inside an event handler writes an event with the incoming hop plus one. A
+ * handler that answers every event with an event, met by another doing the same, would otherwise
+ * write forever; at this depth the emit is refused and logged instead of delivered.
+ */
+export declare const PHIS_ADDON_EVENT_MAX_HOPS = 4;
 /**
  * The Core-owned service kinds an Add-on may implement.
  *

package/dist/core.js

@@ -49,6 +49,8 @@ export const PHIS_CORE_CAPABILITIES = {
     paymentNotifications: "@phis/server/payment-notifications:v1",
     /** Writing to a person about an occasion the Add-on declared, with Core owning frame and transport. */
     notifications: "@phis/server/notifications:v1",
+    /** Announcing an event this Add-on declared under its own name, for the Add-ons of this Site that listen. */
+    events: "@phis/server/events:v1",
 };
 /**
  * What Core tells an Add-on about after the fact.
@@ -72,6 +74,14 @@ export const PHIS_ADDON_EVENTS = {
     threadLinkRemoved: "thread.link.removed",
     paymentChanged: "payment.changed",
 };
+/**
+ * How many Add-ons an event may pass through.
+ *
+ * An Add-on that emits inside an event handler writes an event with the incoming hop plus one. A
+ * handler that answers every event with an event, met by another doing the same, would otherwise
+ * write forever; at this depth the emit is refused and logged instead of delivered.
+ */
+export const PHIS_ADDON_EVENT_MAX_HOPS = 4;
 /**
  * The Core-owned service kinds an Add-on may implement.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phis/contracts",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "license": "Apache-2.0",
   "type": "module",
   "publishConfig": {