@phis/contracts 0.7.3 → 0.7.5

package/README.md

@@ -26,6 +26,15 @@ and change at different moments.
 @phis/contracts/server-capabilities  the capability snapshot phis reports and the UI acts on
 @phis/contracts/site-groups          the membership levels of a Site group, as both ends count them
 @phis/contracts/user-state           the shapes a Module may keep a person's decisions in, and the key grammar
+@phis/contracts/references           the Page reference grammar both sides derive and compare
+@phis/contracts/resource-links       the links from a Phi record into an Add-on's own system
+@phis/contracts/support              the Support ticket vocabulary
+@phis/contracts/threads              the thread vocabulary
+@phis/contracts/conditions           the runtime condition descriptors
+@phis/contracts/controls             the Control descriptors
+@phis/contracts/forms                the Form descriptors and their parsers
+@phis/contracts/layout               the layout vocabulary
+@phis/contracts/timeline             the timeline entries
 ```
 
 ## Before the v1 release, interface versions stay at 1
@@ -61,13 +70,21 @@ 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
   declared, not migrated by hand; phis applies them.
 - **Service kinds** -- the Core-owned kinds an Add-on may supply an implementation of: Media Storage
-  (`PhisMediaStorageAdapter`, upload plans, object I/O) and Directory. `PHIS_SERVICE_KINDS` names them
+  (`PhisMediaStorageAdapter`, upload plans, object I/O), Directory, Payments, Translation and Support
+  Forwarding. `PHIS_SERVICE_KINDS` names them
   and `PHIS_SERVICE_INTERFACE_DIGESTS` holds the digest of each kind's current interface; Core refuses an
   Add-on built against a different digest at install.
 - **Core capabilities** -- `PHIS_CORE_CAPABILITIES`, the catalogue ids an Add-on may require. Declare
@@ -175,7 +192,8 @@ URL is built stays with each side, and phis's numeric Space kind never reaches a
 ## `/http`
 
 The request header names phis reads and the site UI writes: `PHIS_TOKEN_HEADER` (`x-phis-token`),
-`PHIS_SITE_KEY_HEADER`, `PHIS_AREA_HEADER`, `PHIS_REQUEST_PATH_HEADER` and `PHIS_REQUEST_SEARCH_HEADER`.
+`PHIS_SITE_KEY_HEADER`, `PHIS_AREA_HEADER`, `PHIS_REQUEST_PATH_HEADER`, `PHIS_REQUEST_SEARCH_HEADER` and
+`PHIS_FORM_RELAY_HEADER`.
 A disagreement here is not a type error but a 403 or 400 at runtime.
 
 ## `/locale`

package/dist/access.d.ts

@@ -85,7 +85,6 @@ export declare const PhiUserEmailSource: {
     readonly GitHub: 23;
 };
 export type PhiUserEmailSourceValue = (typeof PhiUserEmailSource)[keyof typeof PhiUserEmailSource];
-export declare function isPhiUserEmailSource(value: unknown): value is PhiUserEmailSourceValue;
 /**
  * Which source a login provider's key stands for.
  *
@@ -168,6 +167,10 @@ export declare function canPhiAccessSubjectReach(subject: PhiAccessSubject, poli
  * keeping stable.
  */
 export declare function isPhiAccessPolicyProviderOwned(policy: PhiViewerAccessPolicy, ownerProviderId?: PhiRoleProviderId | null): boolean;
+/** Whether a value is a provider id: `@scope/name`, with further segments allowed. */
+export declare function isPhiProviderId(value: unknown): value is `@${string}/${string}`;
+/** Whether a value is a Site group key, as `phis.site_groups.key` accepts it. */
+export declare function isPhiSiteGroupKey(value: unknown): value is string;
 /**
  * Reads a stored descriptor back into a policy, or null.
  *

package/dist/access.js

@@ -84,10 +84,6 @@ export const PhiUserEmailSource = {
     Microsoft: 22,
     GitHub: 23,
 };
-export function isPhiUserEmailSource(value) {
-    return typeof value === "number"
-        && Object.values(PhiUserEmailSource).includes(value);
-}
 /**
  * Which source a login provider's key stands for.
  *
@@ -182,6 +178,14 @@ export function isPhiAccessPolicyProviderOwned(policy, ownerProviderId) {
 }
 const PROVIDER_ID_PATTERN = /^@[^/]+\/[^/]+(?:\/[^/]+)*$/;
 const GROUP_KEY_PATTERN = /^[a-z0-9][a-z0-9._-]{0,159}$/u;
+/** Whether a value is a provider id: `@scope/name`, with further segments allowed. */
+export function isPhiProviderId(value) {
+    return typeof value === "string" && PROVIDER_ID_PATTERN.test(value);
+}
+/** Whether a value is a Site group key, as `phis.site_groups.key` accepts it. */
+export function isPhiSiteGroupKey(value) {
+    return typeof value === "string" && GROUP_KEY_PATTERN.test(value);
+}
 /** The same shape an Add-on manifest may declare a role under. */
 const ADDON_ROLE_NAME_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
 /**

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/dist/media-storage.d.ts

@@ -294,7 +294,7 @@ export type PhiMediaUploadCompletionInput = {
  */
 export declare const PHIS_MEDIA_CHECKSUM_ALGORITHMS: readonly ["sha256", "sha512", "sha256-composite", "xxhash128", "crc64nvme", "crc32c", "crc32", "md5"];
 export type PhisMediaChecksumAlgorithm = (typeof PHIS_MEDIA_CHECKSUM_ALGORITHMS)[number];
-export { PHIS_MEDIA_UPLOAD_MAX_PART_COUNT, PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES, formatPhiMediaCompositeChecksum, parsePhiMediaCompositeChecksum, resolvePhiMediaUploadPartCount, resolvePhiMediaUploadPartSizeBytes, } from "./media.js";
+export { PHIS_MEDIA_UPLOAD_MAX_PART_COUNT, PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES, formatPhiMediaCompositeChecksum, resolvePhiMediaUploadPartCount, resolvePhiMediaUploadPartSizeBytes, } from "./media.js";
 /**
  * The digests strong enough to answer "is this the same file", rather than only "did it arrive intact".
  *

package/dist/media-storage.js

@@ -36,7 +36,7 @@ export const PHIS_MEDIA_CHECKSUM_ALGORITHMS = [
  * that request is signed. So the rule cannot sit behind the Add-on surface, and it must not be written
  * twice -- two copies of a division are two divisions the day one of them is edited.
  */
-export { PHIS_MEDIA_UPLOAD_MAX_PART_COUNT, PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES, formatPhiMediaCompositeChecksum, parsePhiMediaCompositeChecksum, resolvePhiMediaUploadPartCount, resolvePhiMediaUploadPartSizeBytes, } from "./media.js";
+export { PHIS_MEDIA_UPLOAD_MAX_PART_COUNT, PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES, formatPhiMediaCompositeChecksum, resolvePhiMediaUploadPartCount, resolvePhiMediaUploadPartSizeBytes, } from "./media.js";
 /**
  * The digests strong enough to answer "is this the same file", rather than only "did it arrive intact".
  *

package/dist/media.d.ts

@@ -265,8 +265,3 @@ export declare function resolvePhiMediaUploadPartCount(sizeBytes: number): numbe
  * SHA-256 that simply failed to match. Naming the division makes a mismatch legible instead of puzzling.
  */
 export declare function formatPhiMediaCompositeChecksum(digestHex: string, partCount: number, partSizeBytes: number): string;
-export declare function parsePhiMediaCompositeChecksum(value: string): {
-    digest: string;
-    partCount: number;
-    partSizeBytes: number;
-} | null;

package/dist/media.js

@@ -409,13 +409,3 @@ export function resolvePhiMediaUploadPartCount(sizeBytes) {
 export function formatPhiMediaCompositeChecksum(digestHex, partCount, partSizeBytes) {
     return `${digestHex.toLowerCase()}-${partCount}-${partSizeBytes}`;
 }
-export function parsePhiMediaCompositeChecksum(value) {
-    const match = /^([0-9a-f]{64})-(\d{1,5})-(\d{1,12})$/u.exec(value.trim().toLowerCase());
-    if (!match)
-        return null;
-    const partCount = Number(match[2]);
-    const partSizeBytes = Number(match[3]);
-    if (partCount < 1 || partSizeBytes < 1)
-        return null;
-    return { digest: match[1], partCount, partSizeBytes };
-}

package/package.json

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