@phis/contracts 0.4.0 → 0.6.0

package/README.md

@@ -6,6 +6,7 @@ and change at different moments.
 
 ```
 @phis/contracts/addon                what phis and a separately shipped Add-on promise each other
+@phis/contracts/payments             the approved Payment consumer, Provider and merchant-profile types
 @phis/contracts/access               the authorization vocabulary phis and @phis/ui both evaluate
 @phis/contracts/signals              the signal vocabulary and address grammar the UI declares in and phis validates
 @phis/contracts/catalog              the Module categories an Add-on declares, the UI groups by and a market filters on
@@ -45,7 +46,7 @@ The types and constants an Add-on declares or implements. Types and constants on
 `server-only`, no React, no Next.
 
 An Add-on is compiled to a single ESM artifact and installed into a running phis through the `phis` CLI;
-it is never built into the server. This subpath is the only thing an Add-on compiles against, and it must
+it is never built into the server. This subpath is the shared Add-on entrypoint it compiles against, and it must
 not depend on phis itself. For an Add-on author it is a build-time dependency: everything it exports is
 erased at compile time apart from a handful of constants.
 
@@ -61,10 +62,10 @@ What it covers:
   (`PhisMediaStorageAdapter`, upload plans, object I/O) and Directory. `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 capability ids an Add-on may require. Declare
-  against these constants rather than spelling the ids out. The list is the vocabulary and may reserve a
-  name before Core delivers it (`resource-links`, `support`); an Add-on that requires a capability this
-  release does not deliver is refused rather than handed a missing object.
+- **Core capabilities** -- `PHIS_CORE_CAPABILITIES`, the catalogue ids an Add-on may require. Declare
+  against these constants rather than spelling the ids out. Core separately validates delivery to
+  Add-ons; a catalogue id such as `authentication` may serve Site Modules without a corresponding
+  Add-on context field. Payment ids accompany the implemented Core capability/service/event catalogue.
 
 `PHIS_ADDON_ABI_VERSION` is the single number phis checks an Add-on against.
 
@@ -72,6 +73,23 @@ How an Add-on is laid out, compiled, installed, activated and upgraded is descri
 [`ADDON_HOWTO.md`](https://github.com/phis-dev/phis-server/blob/main/ADDON_HOWTO.md); the rules behind it
 are in [`SERVER_ADDONS.md`](https://github.com/phis-dev/phis-server/blob/main/SERVER_ADDONS.md).
 
+## `/payments`
+
+The approved v1 consumer capability, Provider adapter, checkout plans, normalized money,
+payment/operation/refund records, merchant profile/grant types and owning-consumer event facts.
+All exports are types; there is no secret accessor implementation, checkout SDK, exchange-rate
+conversion or Payment engine here. The same types are re-exported by `/addon`.
+
+Consumers own their prices in CHF, EUR, USD or another supported currency. Every payment uses one
+currency; capture and refunds inherit it. Core never infers conversion or settlement currency.
+
+Core implements Payment execution separately. Its catalogue exports `payments`, `paymentNotifications`,
+the Payment service kind/interface digest and `payment.changed`. Notification ingress is available
+only in a bound hook context. The Add-on event context discriminates thread and Payment subjects;
+thread producers remain explicitly typed as thread events.
+See the normative [Payment contract](https://github.com/phis-dev/phis-server/blob/main/PAYMENTS.md)
+and [Stripe/profile contract](https://github.com/phis-dev/phis-server/blob/main/PAYMENTS_STRIPE.md).
+
 ## `/access`
 
 Claim shapes, policy shapes, and the evaluator that decides them. Unlike `/addon`, this is runtime code

package/dist/addon-index.d.ts

@@ -3,6 +3,7 @@ export * from "./assets.js";
 export * from "./capabilities.js";
 export * from "./core.js";
 export * from "./media-storage.js";
+export * from "./payments.js";
 export * from "./queries.js";
 export * from "./resource-links.js";
 export * from "./schema.js";

package/dist/addon-index.js

@@ -3,6 +3,7 @@ export * from "./assets.js";
 export * from "./capabilities.js";
 export * from "./core.js";
 export * from "./media-storage.js";
+export * from "./payments.js";
 export * from "./queries.js";
 export * from "./resource-links.js";
 export * from "./schema.js";

package/dist/addon.d.ts

@@ -65,7 +65,9 @@ export type PhisAddonHookDescriptor = {
      *
      * Absent is not a lesser variant of present: an unverified hook writes nothing at all -- not through
      * `data:v1`, not by opening a thread -- because nothing distinguishes its caller from anybody who
-     * found the address. A hook that needs to write declares how it can be believed.
+     * found the address. A hook that needs ambient write authority declares how it can be believed.
+     * Target v1 Payment notification ingress instead verifies through its bound Core capability and
+     * reconciles Core-owned payment state without granting ambient hook write authority.
      */
     verification?: PhisAddonHookVerificationDescriptor;
     /**

package/dist/capabilities.d.ts

@@ -12,7 +12,8 @@
  * at the point where it made the mistake.
  */
 import type { PhisAssetsCapabilityV1 } from "./assets.js";
-import type { PhisAddonEventId } from "./core.js";
+import type { 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";
 import type { PhisSupportCapabilityV1 } from "./support.js";
@@ -102,6 +103,10 @@ export type PhisAddonCapabilities = {
     support?: PhisSupportCapabilityV1;
     settings?: PhisSettingsCapabilityV1;
     roles?: PhisRolesCapabilityV1;
+    /** Bound to the declaring consumer and Site when required. */
+    payments?: PhisPaymentsCapabilityV1;
+    /** Supplied only to an original, bound Payment Provider hook request. */
+    paymentNotifications?: PhisPaymentNotificationsCapabilityV1;
 };
 /**
  * The roles capability: `@phis/server/roles:v1`.
@@ -206,9 +211,19 @@ export type PhisStorageCapabilityV1 = {
  * own would be a package that could plant one.
  */
 export type PhisSecretsCapabilityV1 = {
-    /** The value, or null when the operator has not configured it. */
-    read(name: string): Promise<string | null>;
+    /**
+     * The value, or null when the operator has not configured it.
+     *
+     * `scope` says which of the two an operator can set: `"site"` (the default) is the one set with
+     * `--site` for the Site this call runs on; `"addon"` is the one set without `--site`, shared by every
+     * Site the Add-on runs on -- one credential for one external account, such as a single app
+     * registration. The two are never substituted for each other: a Site secret that is missing is
+     * `null`, not the shared one.
+     */
+    read(name: string, scope?: PhisSecretScope): Promise<string | null>;
 };
+/** Which secret `PhisSecretsCapabilityV1.read` names: the Site's own, or the one shared by all Sites. */
+export type PhisSecretScope = "site" | "addon";
 /**
  * What an Add-on may learn about a person.
  *
@@ -357,24 +372,26 @@ export type PhisAddonJobContext = {
  * this Site something, an event is this Site telling an Add-on something, and both run as the Add-on
  * rather than as a person.
  *
- * Delivery is bounded by the same link. An Add-on is told about a thread it is synced with and about no
- * other, because a Site-wide feed of everything anybody writes is the listing `threads:v1` refuses,
- * arriving by push instead of by pull.
+ * Thread delivery is bounded by a synced link. The Payment event reaches only its stored
+ * consuming Add-on. The subject kind and event discriminate those two ownership models; approved
+ * Payment facts are delivered through Core's durable owner-directed outbox.
  */
-export type PhisAddonEventContext = {
+export type PhisAddonEventFacts = {
+    event: PhisAddonThreadEventId;
+    subject: {
+        kind: "thread";
+        threadId: number;
+        messageId: number | null;
+    };
+} | PhisPaymentChangedEventFacts;
+export type PhisAddonEventContext = PhisAddonEventFacts & {
     addonId: string;
-    event: PhisAddonEventId;
     /** This delivery, stable across retries, so a handler can recognise one it already settled. */
     deliveryId: string;
     site: {
         id: number;
         key: string;
     };
-    /** The thread the event happened in, and the message where the event is about one. */
-    subject: {
-        threadId: number;
-        messageId: number | null;
-    };
     capabilities: PhisAddonCapabilities;
     signal: AbortSignal;
 };

package/dist/catalog.d.ts

@@ -1,3 +1,4 @@
+import { type PhiCmsAreaKey } from "./cms.js";
 /**
  * What a Module is for, as an operator reads it on the Modules page.
  *
@@ -64,6 +65,19 @@ export type PhisModulePackageEntry = {
      * asks at intake, where refusing costs the publisher a message rather than the operator a page.
      */
     category: string;
+    /**
+     * The Areas the Module may serve, and the only place a package states them.
+     *
+     * Here and not in the Module's definition, because the reader that needs them first cannot run the
+     * definition: `phis module` writes one Client projection per Area and must know, without loading a
+     * stranger's code, which packages' Client doors belong in which. A definition that stated them as
+     * well would be a second answer that can disagree with this one; the generated projection hands
+     * these to the definition instead.
+     *
+     * Membership, unlike the category: an Area is a place the Site renders, and one this build has no
+     * place for cannot be served at all.
+     */
+    eligibleAreas: PhiCmsAreaKey[];
 };
 /**
  * What a Module package says about itself, without being run.

package/dist/catalog.js

@@ -1,3 +1,4 @@
+import { isPhiCmsAreaKey } from "./cms.js";
 /**
  * What a Module is for, as an operator reads it on the Modules page.
  *
@@ -103,14 +104,25 @@ export function readPhisModulePackageDeclaration(packageJson) {
         if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
             throw new Error(`"${at}" must be an object.`);
         }
-        const { moduleId, category } = entry;
+        const { moduleId, category, eligibleAreas } = entry;
         if (typeof moduleId !== "string" || !moduleId.trim()) {
             throw new Error(`"${at}.moduleId" must be a non-empty string.`);
         }
         if (typeof category !== "string" || !category.trim()) {
             throw new Error(`"${at}.category" must be a non-empty string.`);
         }
-        return { moduleId, category };
+        if (!Array.isArray(eligibleAreas) || eligibleAreas.length === 0) {
+            throw new Error(`"${at}.eligibleAreas" must name at least one Area.`);
+        }
+        for (const area of eligibleAreas) {
+            if (!isPhiCmsAreaKey(area)) {
+                throw new Error(`"${at}.eligibleAreas" names "${String(area)}", which is not an Area.`);
+            }
+        }
+        if (new Set(eligibleAreas).size !== eligibleAreas.length) {
+            throw new Error(`"${at}.eligibleAreas" names an Area twice.`);
+        }
+        return { moduleId, category, eligibleAreas: [...eligibleAreas] };
     });
     return { sourceLocale: typeof sourceLocale === "string" ? sourceLocale : null, modules };
 }

package/dist/cms.d.ts

@@ -50,6 +50,17 @@ export type PhiCmsRegionTypeValue = (typeof PhiCmsRegionType)[keyof typeof PhiCm
  * Bits 2, 5 and 7 are unassigned. That is what makes the numbers worth stating once: 8 reads like the
  * fourth Area and is the third, and phi-server stores it as `area_id` where nothing spells it out.
  */
+/**
+ * The Areas a Site has, by name.
+ *
+ * The numbering below already lived here, because both sides store it and a renumbering neither of
+ * them noticed would put a Page in a different Area than it was written into. The names are the same
+ * agreement read the other way round and stood in two more copies -- one per repository -- so a Site
+ * that gained an Area would have had to gain it three times.
+ */
+export declare const PHI_CMS_AREA_KEYS: readonly ["public", "app", "admin", "builder", "editor", "accounting"];
+export type PhiCmsAreaKey = (typeof PHI_CMS_AREA_KEYS)[number];
+export declare function isPhiCmsAreaKey(value: unknown): value is PhiCmsAreaKey;
 export declare const PhiCmsVisibilityContext: {
     readonly PublicArea: number;
     readonly AppArea: number;
@@ -62,7 +73,9 @@ export declare const PhiCmsVisibilityContext: {
  * The flags a CMS row carries, in the one numbering both sides read them from.
  *
  * Not every flag reaches every kind of row -- `Collapsed` is a Region's answer and `MobileOnly` a
- * renderable's -- but they share one space, because a row is stored as a row whatever it holds.
+ * renderable's -- but they share one space, because a row is stored as a row whatever it holds. The
+ * same numbering serves a config's own `flags`, where a Region's and an Overlay's behaviour live
+ * (`Sticky`, `NoCloseButton`, ...): a yes-or-no answer in a stored record is a bit, never a boolean.
  *
  * `NoIndex` is a Page's, and it is the Site's answer rather than the preset's: a Module states what a
  * Page it ships starts out as, and the Builder's switch is what decides from then on. That is why it
@@ -77,6 +90,26 @@ export declare const PhiCmsFlags: {
     readonly Collapsed: number;
     readonly NoTranslate: number;
     readonly NoIndex: number;
+    /** Stays in view while the page scrolls (Header and Sider families). */
+    readonly Sticky: number;
+    /** A Sider that takes the viewport height below its offset. */
+    readonly FullHeight: number;
+    /** A Sider the viewer can fold to its collapsed width. */
+    readonly Collapsible: number;
+    /** The Header chrome renders no close button. */
+    readonly NoCloseButton: number;
+    /** Escape does not request dismissal. */
+    readonly NoEscapeClose: number;
+    /** A Modal centred in the viewport. */
+    readonly Centered: number;
+    /** A Drawer the viewer can resize. */
+    readonly Resizable: number;
+    /** A Drawer that pushes a nested Drawer aside (`pushDistance` states how far). */
+    readonly Push: number;
+    /** Pointer input reaches the page behind the Overlay. */
+    readonly MaskPassesPointer: number;
+    /** An outside pointer action does not request dismissal. */
+    readonly MaskKeepsOpen: number;
 };
 export declare const PhiCmsRevisionFlags: {
     readonly Draft: number;

package/dist/cms.js

@@ -49,6 +49,26 @@ export const PhiCmsRegionType = {
  * Bits 2, 5 and 7 are unassigned. That is what makes the numbers worth stating once: 8 reads like the
  * fourth Area and is the third, and phi-server stores it as `area_id` where nothing spells it out.
  */
+/**
+ * The Areas a Site has, by name.
+ *
+ * The numbering below already lived here, because both sides store it and a renumbering neither of
+ * them noticed would put a Page in a different Area than it was written into. The names are the same
+ * agreement read the other way round and stood in two more copies -- one per repository -- so a Site
+ * that gained an Area would have had to gain it three times.
+ */
+export const PHI_CMS_AREA_KEYS = [
+    "public",
+    "app",
+    "admin",
+    "builder",
+    "editor",
+    "accounting",
+];
+const PHI_CMS_AREA_KEY_SET = new Set(PHI_CMS_AREA_KEYS);
+export function isPhiCmsAreaKey(value) {
+    return typeof value === "string" && PHI_CMS_AREA_KEY_SET.has(value);
+}
 export const PhiCmsVisibilityContext = {
     PublicArea: 1 << 0,
     AppArea: 1 << 1,
@@ -61,7 +81,9 @@ export const PhiCmsVisibilityContext = {
  * The flags a CMS row carries, in the one numbering both sides read them from.
  *
  * Not every flag reaches every kind of row -- `Collapsed` is a Region's answer and `MobileOnly` a
- * renderable's -- but they share one space, because a row is stored as a row whatever it holds.
+ * renderable's -- but they share one space, because a row is stored as a row whatever it holds. The
+ * same numbering serves a config's own `flags`, where a Region's and an Overlay's behaviour live
+ * (`Sticky`, `NoCloseButton`, ...): a yes-or-no answer in a stored record is a bit, never a boolean.
  *
  * `NoIndex` is a Page's, and it is the Site's answer rather than the preset's: a Module states what a
  * Page it ships starts out as, and the Builder's switch is what decides from then on. That is why it
@@ -76,6 +98,35 @@ export const PhiCmsFlags = {
     Collapsed: 1 << 4,
     NoTranslate: 1 << 5,
     NoIndex: 1 << 6,
+    /*
+     * A Region's behaviour, carried in its config's `flags`: a Region stored on a Page is a config under
+     * the Page's `layoutConfig` and has no row of its own, so the config is the one place both kinds have.
+     */
+    /** Stays in view while the page scrolls (Header and Sider families). */
+    Sticky: 1 << 7,
+    /** A Sider that takes the viewport height below its offset. */
+    FullHeight: 1 << 8,
+    /** A Sider the viewer can fold to its collapsed width. */
+    Collapsible: 1 << 9,
+    /*
+     * An Overlay's behaviour, carried in its config's `flags` the same way. The bits name the departure
+     * from the Overlay's defaults, so an unset flag set is the plain Overlay: a close button, Escape
+     * closes, the mask stops the pointer and closes on a click.
+     */
+    /** The Header chrome renders no close button. */
+    NoCloseButton: 1 << 10,
+    /** Escape does not request dismissal. */
+    NoEscapeClose: 1 << 11,
+    /** A Modal centred in the viewport. */
+    Centered: 1 << 12,
+    /** A Drawer the viewer can resize. */
+    Resizable: 1 << 13,
+    /** A Drawer that pushes a nested Drawer aside (`pushDistance` states how far). */
+    Push: 1 << 14,
+    /** Pointer input reaches the page behind the Overlay. */
+    MaskPassesPointer: 1 << 15,
+    /** An outside pointer action does not request dismissal. */
+    MaskKeepsOpen: 1 << 16,
 };
 export const PhiCmsRevisionFlags = {
     Draft: 1 << 0,

package/dist/conditions.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The grammar of a runtime condition: when a Widget shows, when a Form field is visible or disabled.
+ *
+ * Stored inside descriptors phis-server keeps, a Form's `visibleWhen` among them, so it is read here and
+ * read once -- the renderer evaluates what the server accepted, by the same rules.
+ */
+import { type PhiControllerSignalAddress, type PhiSignalAddress } from "./signals.js";
+/**
+ * Where a condition reads the value it judges.
+ *
+ * `row`, `form`, `controller` and `widget` are values the page produced: a record under the cursor, what
+ * has been typed, what a Controller holds, what a neighbouring Widget found out. `feature` is what this
+ * Site was configured to have -- a named fact a Module publishes about its own setup, such as whether a
+ * sign-in method is switched on, settled before anything renders and never seen by the browser. `page`
+ * is the one the visitor arrived with --
+ * the address of the page they opened, which is state as much as any of the others and the only kind
+ * that is already settled before the first Widget renders. A confirmation link carries its token there,
+ * an external login returns with its outcome there, and a Widget that should appear only for one of
+ * those can say so without a component of its own to read the query string.
+ */
+export declare const PHI_RUNTIME_CONDITION_SOURCES: readonly ["row", "form", "controller", "page", "widget", "feature"];
+export declare const PHI_RUNTIME_CONDITION_OPERATORS: readonly ["truthy", "falsy", "equals", "contains"];
+export declare const PHI_RUNTIME_CONDITION_GROUP_MATCHES: readonly ["all", "any"];
+export type PhiRuntimeConditionSource = (typeof PHI_RUNTIME_CONDITION_SOURCES)[number];
+export type PhiRuntimeConditionOperator = (typeof PHI_RUNTIME_CONDITION_OPERATORS)[number];
+export type PhiRuntimeConditionGroupMatch = (typeof PHI_RUNTIME_CONDITION_GROUP_MATCHES)[number];
+export type PhiRuntimeConditionValue = string;
+export type PhiRuntimeValueCondition = {
+    source: PhiRuntimeConditionSource;
+    controllerAddress?: PhiControllerSignalAddress;
+    /**
+     * Which Widget is being asked, for a `widget` condition.
+     *
+     * A Controller is state that outlives the Widgets reading it; a Widget reports only what it found out
+     * for itself. Both answer on the same channel, so a Widget beside another one -- a preview of what a
+     * link will do, next to the form that does it -- needs no Controller of its own to be composed with.
+     */
+    widgetAddress?: PhiSignalAddress;
+    valuePath: string;
+    operator: PhiRuntimeConditionOperator;
+    value?: PhiRuntimeConditionValue;
+    /**
+     * How to read a sender that has not said anything yet. Absent means "not matched".
+     *
+     * Hiding until told is right for a fact that is being fetched: a form that spends a confirmation link
+     * must not appear before the link has been checked. It is wrong for a state that only a later action
+     * can bring about -- nobody is halfway through a second authentication factor when the page opens, so
+     * a Widget standing back "while a step is under way" would stand back forever, waiting for a report
+     * that nothing is happening.
+     */
+    whenUnavailable?: PhiRuntimeConditionResult;
+    reason?: string;
+};
+export type PhiRuntimeConditionExpression = PhiRuntimeValueCondition | {
+    match: PhiRuntimeConditionGroupMatch;
+    conditions: readonly PhiRuntimeConditionExpression[];
+};
+export type PhiRuntimeConditionResult = "matched" | "not-matched" | "unavailable";
+/**
+ * The address of the page as the visitor opened it, which is what a `page` condition reads.
+ *
+ * A missing query parameter is an answer rather than a gap: `falsy` on `query.token` matches on the
+ * page without one, which is how a form with two stages knows which of them it is on.
+ */
+export type PhiRuntimePageConditionState = {
+    path: string;
+    query: Readonly<Record<string, string>>;
+};
+/**
+ * What the active Modules report about this Site's configuration, by namespaced name.
+ *
+ * A Module publishes these the way it publishes signal capabilities: deliberately, under a name it
+ * keeps. A condition reads `auth.password`, not a field of somebody's internal context, so renaming
+ * something inside a Module cannot silently change which Widgets a page shows.
+ */
+export type PhiRuntimeFeatureState = Readonly<Record<string, unknown>>;
+export type PhiRuntimeConditionSourceValues = {
+    row?: Record<string, unknown> | null;
+    features?: PhiRuntimeFeatureState | null;
+    form?: Record<string, unknown> | null;
+    controllers?: Readonly<Record<string, Record<string, unknown>>> | null;
+    /** Reported by Widgets, keyed by the address each one sends from. */
+    widgets?: Readonly<Record<string, Record<string, unknown>>> | null;
+    page?: PhiRuntimePageConditionState | null;
+};
+export type PhiRuntimeConditionStateSignalValue = {
+    state: Record<string, unknown>;
+};
+export declare function readPhiRuntimeValueCondition(value: unknown): PhiRuntimeValueCondition | null;
+export declare function readPhiRuntimeConditionExpression(value: unknown): PhiRuntimeConditionExpression | null;
+export declare function collectPhiRuntimeValueConditions(expression: PhiRuntimeConditionExpression | null | undefined): PhiRuntimeValueCondition[];
+export declare function combinePhiRuntimeConditionExpressions(match: PhiRuntimeConditionGroupMatch, expressions: readonly (PhiRuntimeConditionExpression | null | undefined)[]): PhiRuntimeConditionExpression | undefined;
+export declare function readPhiRuntimeConditionStateSignalValue(value: unknown): PhiRuntimeConditionStateSignalValue | null;
+export declare function readPhiRuntimeConditionValue(input: unknown, valuePath: string): unknown;
+export declare function matchesPhiRuntimeValueCondition(condition: PhiRuntimeValueCondition, sources: PhiRuntimeConditionSourceValues): boolean;
+export declare function evaluatePhiRuntimeConditionExpression(expression: PhiRuntimeConditionExpression, sources: PhiRuntimeConditionSourceValues): PhiRuntimeConditionResult;

package/dist/conditions.js

@@ -0,0 +1,163 @@
+/**
+ * The grammar of a runtime condition: when a Widget shows, when a Form field is visible or disabled.
+ *
+ * Stored inside descriptors phis-server keeps, a Form's `visibleWhen` among them, so it is read here and
+ * read once -- the renderer evaluates what the server accepted, by the same rules.
+ */
+import { readPhiControllerSignalAddress, readPhiSignalAddress, } from "./signals.js";
+import { isPhiRecord, readPhiDotPath } from "./record.js";
+/**
+ * Where a condition reads the value it judges.
+ *
+ * `row`, `form`, `controller` and `widget` are values the page produced: a record under the cursor, what
+ * has been typed, what a Controller holds, what a neighbouring Widget found out. `feature` is what this
+ * Site was configured to have -- a named fact a Module publishes about its own setup, such as whether a
+ * sign-in method is switched on, settled before anything renders and never seen by the browser. `page`
+ * is the one the visitor arrived with --
+ * the address of the page they opened, which is state as much as any of the others and the only kind
+ * that is already settled before the first Widget renders. A confirmation link carries its token there,
+ * an external login returns with its outcome there, and a Widget that should appear only for one of
+ * those can say so without a component of its own to read the query string.
+ */
+export const PHI_RUNTIME_CONDITION_SOURCES = ["row", "form", "controller", "page", "widget", "feature"];
+export const PHI_RUNTIME_CONDITION_OPERATORS = ["truthy", "falsy", "equals", "contains"];
+export const PHI_RUNTIME_CONDITION_GROUP_MATCHES = ["all", "any"];
+function readConditionValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function readConditionSource(value) {
+    return PHI_RUNTIME_CONDITION_SOURCES.includes(value)
+        ? value
+        : null;
+}
+export function readPhiRuntimeValueCondition(value) {
+    if (!isPhiRecord(value))
+        return null;
+    const source = readConditionSource(value.source);
+    const operator = value.operator === "truthy" || value.operator === "falsy" ||
+        value.operator === "equals" || value.operator === "contains"
+        ? value.operator
+        : null;
+    const valuePath = typeof value.valuePath === "string" ? value.valuePath.trim() : "";
+    const whenUnavailable = value.whenUnavailable === "matched" || value.whenUnavailable === "not-matched"
+        ? value.whenUnavailable
+        : undefined;
+    const controllerAddress = source === "controller"
+        ? readPhiControllerSignalAddress(value.controllerAddress)
+        : undefined;
+    const widgetAddress = source === "widget"
+        ? readPhiSignalAddress(value.widgetAddress)
+        : undefined;
+    const conditionValue = readConditionValue(value.value);
+    if (!source ||
+        !operator ||
+        !valuePath ||
+        (source === "controller" && !controllerAddress) ||
+        (source === "widget" && !widgetAddress) ||
+        (operator !== "truthy" && operator !== "falsy" && conditionValue === undefined)) {
+        return null;
+    }
+    return {
+        source,
+        controllerAddress,
+        widgetAddress,
+        valuePath,
+        operator,
+        whenUnavailable,
+        value: operator === "truthy" || operator === "falsy" ? undefined : conditionValue,
+        reason: typeof value.reason === "string" && value.reason.trim() ? value.reason.trim() : undefined,
+    };
+}
+export function readPhiRuntimeConditionExpression(value) {
+    const leaf = readPhiRuntimeValueCondition(value);
+    if (leaf)
+        return leaf;
+    if (!isPhiRecord(value) || (value.match !== "all" && value.match !== "any") || !Array.isArray(value.conditions)) {
+        return null;
+    }
+    const conditions = value.conditions.map(readPhiRuntimeConditionExpression);
+    if (conditions.length === 0 || conditions.some((condition) => condition == null)) {
+        return null;
+    }
+    return {
+        match: value.match,
+        conditions: conditions,
+    };
+}
+export function collectPhiRuntimeValueConditions(expression) {
+    if (!expression)
+        return [];
+    if ("source" in expression)
+        return [expression];
+    return expression.conditions.flatMap(collectPhiRuntimeValueConditions);
+}
+export function combinePhiRuntimeConditionExpressions(match, expressions) {
+    const conditions = expressions.filter((entry) => Boolean(entry));
+    if (conditions.length === 0)
+        return undefined;
+    if (conditions.length === 1)
+        return conditions[0];
+    return { match, conditions };
+}
+export function readPhiRuntimeConditionStateSignalValue(value) {
+    return isPhiRecord(value) && isPhiRecord(value.state) ? { state: value.state } : null;
+}
+export function readPhiRuntimeConditionValue(input, valuePath) {
+    return readPhiDotPath(input, valuePath);
+}
+function resolvePhiRuntimeConditionSource(condition, sources) {
+    if (condition.source === "row")
+        return sources.row ?? null;
+    if (condition.source === "form")
+        return sources.form ?? null;
+    if (condition.source === "page")
+        return sources.page ?? null;
+    if (condition.source === "feature")
+        return sources.features ?? null;
+    if (condition.source === "widget") {
+        return condition.widgetAddress ? sources.widgets?.[condition.widgetAddress] ?? null : null;
+    }
+    return condition.controllerAddress
+        ? sources.controllers?.[condition.controllerAddress] ?? null
+        : null;
+}
+export function matchesPhiRuntimeValueCondition(condition, sources) {
+    const source = resolvePhiRuntimeConditionSource(condition, sources);
+    if (source == null)
+        return false;
+    const current = readPhiRuntimeConditionValue(source, condition.valuePath);
+    if ((condition.source === "controller" || condition.source === "widget") && current === undefined)
+        return false;
+    if (condition.operator === "truthy")
+        return Boolean(current);
+    if (condition.operator === "falsy")
+        return !current;
+    if (condition.operator === "equals")
+        return Object.is(current, condition.value);
+    return Array.isArray(current)
+        ? current.some((entry) => typeof entry === "string" && entry === condition.value)
+        : typeof current === "string" && typeof condition.value === "string"
+            ? current.includes(condition.value)
+            : false;
+}
+export function evaluatePhiRuntimeConditionExpression(expression, sources) {
+    if ("source" in expression) {
+        const source = resolvePhiRuntimeConditionSource(expression, sources);
+        if (source == null)
+            return expression.whenUnavailable ?? "unavailable";
+        if ((expression.source === "controller" || expression.source === "widget") &&
+            readPhiRuntimeConditionValue(source, expression.valuePath) === undefined) {
+            return expression.whenUnavailable ?? "unavailable";
+        }
+        return matchesPhiRuntimeValueCondition(expression, sources) ? "matched" : "not-matched";
+    }
+    const results = expression.conditions.map((condition) => evaluatePhiRuntimeConditionExpression(condition, sources));
+    if (expression.match === "all") {
+        if (results.some((result) => result === "not-matched"))
+            return "not-matched";
+        return results.every((result) => result === "matched") ? "matched" : "unavailable";
+    }
+    if (results.some((result) => result === "matched"))
+        return "matched";
+    return results.every((result) => result === "not-matched") ? "not-matched" : "unavailable";
+}