@phis/contracts 0.2.0 → 0.3.1

package/dist/schema.d.ts

@@ -10,16 +10,16 @@
  * exactly what this removes. An Add-on that needs one of them is either cut wrong or needs a Core
  * service.
  */
-export declare const PHI_SERVER_ADDON_SCHEMA_DESCRIPTOR_VERSION: 1;
+export declare const PHIS_ADDON_SCHEMA_DESCRIPTOR_VERSION: 1;
 /**
  * What a column holds, said abstractly so Core can map it.
  *
  * `identity` is a generated key and may appear only in a primary key; the width is Core's business, not
  * the Add-on's.
  */
-export type PhiServerAddonColumnType = "identity" | "smallInteger" | "integer" | "bigInteger" | "text" | "string" | "boolean" | "instant" | "json" | "uuid" | "binary";
+export type PhisAddonColumnType = "identity" | "smallInteger" | "integer" | "bigInteger" | "text" | "string" | "boolean" | "instant" | "json" | "uuid" | "binary";
 /** The closed vocabulary a default may be drawn from. Anything wider would be an expression. */
-export type PhiServerAddonColumnDefault = {
+export type PhisAddonColumnDefault = {
     kind: "literal";
     value: string | number | boolean;
 } | {
@@ -36,27 +36,45 @@ export type PhiServerAddonColumnDefault = {
  * binds the pair rather than the id alone. Core never references a group any other way, and an Add-on
  * that could would be able to name a group belonging to a different Site.
  */
-export declare const PHI_SERVER_ADDON_CORE_REFERENCES: {
+export declare const PHIS_ADDON_CORE_REFERENCES: {
     readonly site: "core.site";
     readonly user: "core.user";
     readonly group: "core.group";
+    /**
+     * A stored file, which is the one Core row an Add-on points at without having written it.
+     *
+     * Core keeps the facts about an object -- where it is, how big, what type, which digest -- in one
+     * place for every upload it has ever handled, whoever asked. An Add-on's asset row names one of them
+     * and holds nothing about it, so there is no second copy to fall out of step, and no key an Add-on
+     * could pass anywhere.
+     */
+    readonly mediaAsset: "core.mediaAsset";
 };
-export type PhiServerAddonCoreReference = (typeof PHI_SERVER_ADDON_CORE_REFERENCES)[keyof typeof PHI_SERVER_ADDON_CORE_REFERENCES];
+export type PhisAddonCoreReference = (typeof PHIS_ADDON_CORE_REFERENCES)[keyof typeof PHIS_ADDON_CORE_REFERENCES];
 /**
  * A delete rule, offered as two values and no third.
  *
  * An Add-on must not be able to refuse a Core deletion: an operator who cannot delete a user because an
  * installed package forbids it is looking at a constraint error from code they may not know they have.
  */
-export type PhiServerAddonDeleteRule = "cascade" | "setNull";
-export type PhiServerAddonValueColumnDescriptor = {
+export type PhisAddonDeleteRule = "cascade" | "setNull";
+export type PhisAddonValueColumnDescriptor = {
     name: string;
-    type: PhiServerAddonColumnType;
+    type: PhisAddonColumnType;
     /** Required for `string`, forbidden otherwise. */
     maxLength?: number;
     nullable?: boolean;
+    /**
+     * Unique -- within the Site, when the table is Site-scoped.
+     *
+     * Core prepends the Site column, because the Add-on cannot: it may not declare `site_id` and so has
+     * nowhere to name the pair. Without that, uniqueness would reach across every tenant on the instance,
+     * and the second Site to install the Add-on would collide with the first over a value neither of them
+     * can see. Instance-wide uniqueness is therefore not expressible on a Site-scoped table, which is the
+     * intended answer rather than a missing feature.
+     */
     unique?: boolean;
-    default?: PhiServerAddonColumnDefault;
+    default?: PhisAddonColumnDefault;
 };
 /**
  * A column that points at something, and therefore has no type of its own.
@@ -66,18 +84,25 @@ export type PhiServerAddonValueColumnDescriptor = {
  * shape a foreign key takes -- there is no separate list of them, and no composite key, because a
  * reference that needs two columns is pointing at something an Add-on should not be reaching into.
  */
-export type PhiServerAddonReferenceColumnDescriptor = {
+export type PhisAddonReferenceColumnDescriptor = {
     name: string;
-    /** A Core table under its symbolic name, or one of this Add-on's own tables. */
-    references: PhiServerAddonCoreReference | {
+    /**
+     * A Core table under its symbolic name, or one of this Add-on's own tables.
+     *
+     * A reference to a Site-scoped table is bound together with its Site, the way a group reference is:
+     * Core writes `(column, site_id)` against the target's `(key, site_id)`, and both tables must be
+     * Site-scoped. The id alone would let a row of one Site name a row of another, and nothing about the
+     * declaration would show it -- the column would look exactly the same and the constraint would hold.
+     */
+    references: PhisAddonCoreReference | {
         table: string;
     };
     nullable?: boolean;
     unique?: boolean;
     /** `setNull` requires a nullable column. */
-    onDelete: PhiServerAddonDeleteRule;
+    onDelete: PhisAddonDeleteRule;
 };
-export type PhiServerAddonColumnDescriptor = PhiServerAddonValueColumnDescriptor | PhiServerAddonReferenceColumnDescriptor;
+export type PhisAddonColumnDescriptor = PhisAddonValueColumnDescriptor | PhisAddonReferenceColumnDescriptor;
 /**
  * A constraint, in structured form.
  *
@@ -88,7 +113,7 @@ export type PhiServerAddonColumnDescriptor = PhiServerAddonValueColumnDescriptor
  * Regular expressions are absent on purpose. Their syntax differs between database systems, and taking
  * them would buy back the dependency this file exists to remove.
  */
-export type PhiServerAddonTableConstraintDescriptor = {
+export type PhisAddonTableConstraintDescriptor = {
     kind: "range";
     name: string;
     column: string;
@@ -119,21 +144,115 @@ export type PhiServerAddonTableConstraintDescriptor = {
     columns: string[];
     nonNullCount: number;
 };
-export type PhiServerAddonIndexDescriptor = {
+/**
+ * What an index is for, said abstractly so Core can choose the structure.
+ *
+ * `ordered` is the ordinary one: equality, ranges, and the orderings a paged select runs under.
+ * `text` is for substring search, names exactly one text column, and is what makes `contains` more than
+ * a scan -- measured on 200,000 rows, 72 ms without it and 0.5 ms with. It cannot be unique, because it
+ * indexes fragments rather than values.
+ *
+ * Absent means `ordered`: an index declared before this field existed had not forgotten it.
+ */
+export type PhisAddonIndexKind = "ordered" | "text";
+export type PhisAddonIndexDescriptor = {
     name: string;
+    kind?: PhisAddonIndexKind;
     columns: string[];
+    /**
+     * Unique, and read exactly as `unique` on a column: within the Site, on a Site-scoped table, with the
+     * Site column prepended by Core.
+     *
+     * A non-unique index is only an access path and is left as it was written. Which order helps depends
+     * on the query, and Core does not know it.
+     */
     unique?: boolean;
 };
-export type PhiServerAddonTableDescriptor = {
+/**
+ * A named place on a row where a file belongs.
+ *
+ * The names are the Add-on's -- `logo`, `package`, `screenshots` -- and the set of them is closed, which
+ * is what makes the rest possible. Core can only enforce a size and a type where it knows which slot is
+ * being filled, and it can only tell an abandoned object from a live one where the vocabulary is finite.
+ * An Add-on that needs no files declares none and gets no table.
+ *
+ * The object key is Core's, never the Add-on's. Two rows cannot be made to name the same object, a key
+ * cannot be spelled that reaches outside the Add-on's prefix, and replacing a file writes a new key
+ * rather than overwriting the old -- overwriting destroys the current file before the row that replaces
+ * it is committed, and a new key leaves the old one behind for the sweep to collect.
+ *
+ * Requires `siteScoped`. An object lives in one Site's store, because that is where the Site's Storage
+ * Profile points; a row shared across Sites has no store its file could belong to.
+ */
+export type PhisAddonAssetSlotDescriptor = {
+    name: string;
+    /**
+     * `one` is a slot that holds the current file and forgets the previous one; `many` accumulates.
+     *
+     * Enforced on the finished file only. An upload replacing a `one` slot exists alongside the file it
+     * will replace until it is complete, because the alternative is a row with nothing behind it for as
+     * long as the transfer takes -- and a transfer that fails would have destroyed the file it never
+     * managed to replace.
+     */
+    cardinality: "one" | "many";
+    /** Refused before a byte is accepted, and not raisable by the Add-on that declared it. */
+    maxBytes: number;
+    /**
+     * The exact types this slot takes, as full media types. Empty is not "anything", it is refused.
+     *
+     * Stated per slot rather than per Add-on because the answers differ within one package: a logo is a
+     * handful of image types and a release artifact is one archive type, and a single list wide enough for
+     * both permits an image where the archive goes.
+     */
+    contentTypes: string[];
+    /**
+     * Who may fetch the file once it is there. `public` when absent.
+     *
+     * Stated per slot for the same reason the types are, and the two cases really do differ: the logo on
+     * a listing has to be readable by anyone who can see the listing, and the release artifact behind it
+     * must not be. Declaring it is what stops a package from having to choose one answer for both.
+     *
+     * It is here rather than left to a later setting because an installed package would otherwise carry
+     * whatever the default happened to be, and a file that was public once has been public.
+     */
+    delivery?: "public" | "authenticated" | "internal";
+    /**
+     * A column on the owning table that Core keeps the file's delivery path in.
+     *
+     * Without it, showing a row's picture means asking for its files -- one question per row, so a page
+     * of fifty costs fifty. With it the path arrives with the row, in the statement that was being run
+     * anyway, and a listing is one query again.
+     *
+     * The column is Core's: it is created from this declaration, written when a file is settled, rewritten
+     * when a file replaces it, cleared when it is taken away, and refused as an assignment in every
+     * declared query. An Add-on that could write it could point a row at somebody else's file.
+     *
+     * The path rather than the Media Asset id, because the path is what gets used and the id alone is not
+     * enough to build one: a delivery path carries the cache revision, and reading that back would be the
+     * join this exists to avoid.
+     *
+     * Only on a `one` slot. A slot that accumulates has no single path to mirror, and a column holding the
+     * newest of several would be a fact nobody asked for.
+     */
+    mirrorColumn?: string;
+};
+export type PhisAddonTableDescriptor = {
     name: string;
     /**
-     * Core adds the Site column, its foreign key, and its cascade, and puts the Site filter into every
-     * query that reads this table. The Add-on neither writes the column nor is able to forget it.
+     * Core adds the Site column, its foreign key, and its cascade, puts the Site filter into every query
+     * that reads this table, and prepends it to every uniqueness rule the table declares. The Add-on
+     * neither writes the column nor is able to forget it.
      *
      * This is more than a reference column: it is the boundary a query is compiled against. A table that
      * merely wants to mention a Site uses a reference column instead.
+     *
+     * Required, and required as a word rather than as an absence. `false` is a real answer -- a category
+     * list, a currency table, a set of country codes belong to the Add-on and to no Site -- but it is an
+     * answer somebody has to give. Left optional, the unguarded table is what an author gets for saying
+     * nothing, and every other boundary in this file works the other way round: Core supplies it and the
+     * Add-on cannot forget it. Here it cannot supply it, so it insists on being told.
      */
-    siteScoped?: boolean;
+    siteScoped: boolean;
     /**
      * Core adds the owner column and its foreign key, and answers whether a row belongs to the acting
      * user. The Add-on neither writes the column nor decides what "own" means, which is the point: the
@@ -142,6 +261,12 @@ export type PhiServerAddonTableDescriptor = {
      * The column is nullable and a deleted user leaves it null rather than taking the rows along. A row
      * without an owner therefore belongs to nobody, and no membership level reaches it through ownership.
      *
+     * Requires `siteScoped`, for the reason a group does. Everywhere else Core weighs a person it weighs
+     * them on a Site -- an authorization is read as a pair, and a disabled membership answers no. Ownership
+     * without a Site is the one place that pair would come apart: the same account would reach a row from
+     * a Site it was never admitted to, and the comparison that let it through looked at nothing but a user
+     * id.
+     *
      * This is authority, not history. A table that only wants to record who created a row uses an
      * ordinary `core.user` reference column, which grants nothing.
      */
@@ -155,10 +280,19 @@ export type PhiServerAddonTableDescriptor = {
      * reference column instead.
      */
     groupScoped?: boolean;
-    columns: PhiServerAddonColumnDescriptor[];
+    columns: PhisAddonColumnDescriptor[];
     primaryKey: string[];
-    indexes?: PhiServerAddonIndexDescriptor[];
-    constraints?: PhiServerAddonTableConstraintDescriptor[];
+    indexes?: PhisAddonIndexDescriptor[];
+    constraints?: PhisAddonTableConstraintDescriptor[];
+    /**
+     * The files rows of this table may carry, which Core keeps in a table of its own beside this one.
+     *
+     * A child table rather than a column per slot, because the slots are the Add-on's to name and their
+     * number is the Add-on's to choose -- and because a gallery is a slot with more than one file in it,
+     * which no column can hold. The child cascades: removing a row removes the rows describing its files,
+     * and the objects they named become collectable.
+     */
+    assets?: PhisAddonAssetSlotDescriptor[];
 };
 /**
  * The shape an Add-on's schema should have -- not the steps to reach it.
@@ -166,8 +300,8 @@ export type PhiServerAddonTableDescriptor = {
  * `version` is the schema version the manifest reports, and Core compares this description against the
  * one it recorded to decide what to run.
  */
-export type PhiServerAddonSchemaDescriptor = {
-    descriptorVersion: typeof PHI_SERVER_ADDON_SCHEMA_DESCRIPTOR_VERSION;
+export type PhisAddonSchemaDescriptor = {
+    descriptorVersion: typeof PHIS_ADDON_SCHEMA_DESCRIPTOR_VERSION;
     version: number;
-    tables: PhiServerAddonTableDescriptor[];
+    tables: PhisAddonTableDescriptor[];
 };

package/dist/schema.js

@@ -10,7 +10,7 @@
  * exactly what this removes. An Add-on that needs one of them is either cut wrong or needs a Core
  * service.
  */
-export const PHI_SERVER_ADDON_SCHEMA_DESCRIPTOR_VERSION = 1;
+export const PHIS_ADDON_SCHEMA_DESCRIPTOR_VERSION = 1;
 /**
  * A Core table an Add-on may point at, named symbolically.
  *
@@ -22,8 +22,17 @@ export const PHI_SERVER_ADDON_SCHEMA_DESCRIPTOR_VERSION = 1;
  * binds the pair rather than the id alone. Core never references a group any other way, and an Add-on
  * that could would be able to name a group belonging to a different Site.
  */
-export const PHI_SERVER_ADDON_CORE_REFERENCES = {
+export const PHIS_ADDON_CORE_REFERENCES = {
     site: "core.site",
     user: "core.user",
     group: "core.group",
+    /**
+     * A stored file, which is the one Core row an Add-on points at without having written it.
+     *
+     * Core keeps the facts about an object -- where it is, how big, what type, which digest -- in one
+     * place for every upload it has ever handled, whoever asked. An Add-on's asset row names one of them
+     * and holds nothing about it, so there is no second copy to fall out of step, and no key an Add-on
+     * could pass anywhere.
+     */
+    mediaAsset: "core.mediaAsset",
 };

package/dist/server-capabilities.d.ts

@@ -0,0 +1,37 @@
+/**
+ * What phis says about a capability provider, in the words the site UI reads it with.
+ *
+ * `/api/v1/site/capabilities` reports, per provider, whether what a Site's Modules require is actually
+ * being offered. phis decides the verdict; the UI acts on it, deactivating a Module whose provider is
+ * not `available` and naming the reason in its diagnostics. A verdict one side can produce and the
+ * other cannot recognise is not an error anywhere -- it is a Module that quietly stays off.
+ *
+ * The state was declared twice, once on each side, in the same six words. That is the arrangement that
+ * let the log services drift while both files still compiled, so it lives here now -- and the shape
+ * around it followed, because a snapshot phis only built and the UI only read was the same arrangement
+ * one level up.
+ *
+ * A provider is Core or an Add-on. Core is one itself, and the one most Modules depend on, which is
+ * why nothing here is named for Add-ons.
+ */
+/** `@scope/name` -- Core is `@phis/server/core`. */
+export type PhiCapabilityProviderId = `@${string}/${string}`;
+/** `@scope/name:v<major>` -- a capability at the interface version it is offered under. */
+export type PhiCapabilityId = `@${string}/${string}:v${number}`;
+export type PhiCapabilityState = "available" | "missing" | "disabled" | "incompatible" | "misconfigured" | "unavailable";
+export type PhiCapabilityDescriptor = {
+    id: PhiCapabilityId;
+    interfaceDigest: string;
+};
+export type PhiCapabilityProvider = {
+    providerId: PhiCapabilityProviderId;
+    state: PhiCapabilityState;
+    diagnosticCode: string | null;
+    capabilities: readonly PhiCapabilityDescriptor[];
+};
+export type PhiCapabilitySnapshot = {
+    siteKey: string;
+    releaseBuildId: string | null;
+    buildManifestDigest: string;
+    providers: readonly PhiCapabilityProvider[];
+};

package/dist/server-capabilities.js

@@ -0,0 +1,17 @@
+/**
+ * What phis says about a capability provider, in the words the site UI reads it with.
+ *
+ * `/api/v1/site/capabilities` reports, per provider, whether what a Site's Modules require is actually
+ * being offered. phis decides the verdict; the UI acts on it, deactivating a Module whose provider is
+ * not `available` and naming the reason in its diagnostics. A verdict one side can produce and the
+ * other cannot recognise is not an error anywhere -- it is a Module that quietly stays off.
+ *
+ * The state was declared twice, once on each side, in the same six words. That is the arrangement that
+ * let the log services drift while both files still compiled, so it lives here now -- and the shape
+ * around it followed, because a snapshot phis only built and the UI only read was the same arrangement
+ * one level up.
+ *
+ * A provider is Core or an Add-on. Core is one itself, and the one most Modules depend on, which is
+ * why nothing here is named for Add-ons.
+ */
+export {};

package/dist/signals.d.ts

@@ -10,6 +10,7 @@
  * of widget shapes that belongs to the UI: phi-server checks that a JSON signal names *a* schema, never
  * which one, so the catalogue is not something the two must agree on.
  */
+import { type PhiCmsInstanceId } from "./cms.js";
 export declare const PHI_SIGNAL_SCOPES: readonly ["widget", "layout", "region", "page", "area", "site"];
 export type PhiSignalScope = (typeof PHI_SIGNAL_SCOPES)[number];
 export declare const PHI_SIGNAL_ACTIONS: readonly ["activate", "change", "toggle", "start", "stop", "clear", "open", "close", "reload", "flush", "filter", "drop"];
@@ -34,3 +35,60 @@ export declare function isPhiSignalValueType(value: unknown): value is PhiSignal
  * The last separator wins, because a scoped package name contains one too.
  */
 export declare function isPhiSignalValueSchemaShape(value: unknown): value is PhiSignalValueSchema;
+/**
+ * Whether a string can name an npm package.
+ *
+ * The lexical rule the controller address family starts from, and the one phi-server had copied under
+ * a different name to validate the same addresses. It is the same test `@phis/ui` keeps beside its own
+ * package name for the grammars that do not travel -- module ids, module-scoped keys. If a second
+ * grammar in this package needs it, that is the moment to give it a subpath of its own.
+ */
+export declare function isPhiNpmPackageName(value: string): boolean;
+/**
+ * The address families a signal may name, and nothing else.
+ *
+ * A wiring is stored by the Builder, validated by phi-server on the way in, and delivered by the site
+ * UI at runtime. All three read the same string, so all three have to parse it alike -- and until
+ * 2026-09-07 two of them did it from separate copies, one of which said in its own comment that it
+ * "mirrors the grammar in @phis/ui" because it could not import it.
+ *
+ * `cms:` addresses a Widget or Layout instance, optionally one control inside it. `region:` addresses a
+ * Region of the route's active context. `controller:` addresses one Controller instance in the
+ * namespace of the Module that owns it.
+ */
+export type PhiSignalAddress = `cms:${PhiCmsInstanceId}` | `cms:${PhiCmsInstanceId}:${string}` | `region:${string}` | `controller:${string}/${string}:${string}`;
+export type PhiControllerSignalAddress = Extract<PhiSignalAddress, `controller:${string}`>;
+export type PhiSignalSender = PhiSignalAddress | null;
+export type PhiSignalReceiver = PhiSignalAddress | "broadcast" | null;
+export type PhiSignalAddressFamily = "cms" | "region";
+/**
+ * The one address the Site scope privileges.
+ *
+ * Site-scoped signals reach across Areas, so nothing addressable inside one may be named in that scope
+ * -- no CMS instance, no Region, no broadcast. The Core Runtime Controller is the exception, and both
+ * sides have to name the same string for the rule to mean anything. `@phis/ui` builds it from its own
+ * constants and asserts it matches this one.
+ */
+export declare const PHI_CORE_RUNTIME_CONTROLLER_ADDRESS: PhiControllerSignalAddress;
+export declare function isPhiSignalAddressSegment(value: string): boolean;
+/**
+ * A controller lives in the namespace of the Module that owns it, so a plugin key is either a bare
+ * package name or that package followed by `/modules/<module>/<namespace>`. Foreign packages use
+ * either form; the grammar does not privilege first-party keys.
+ */
+export declare function isPhiControllerPluginKey(value: string): boolean;
+export declare function isPhiControllerSignalAddress(address: unknown): address is PhiControllerSignalAddress;
+/** The instance a `cms:` address names, or null when the string is not one. */
+export declare function readPhiCmsSignalAddressInstanceId(address: string): PhiCmsInstanceId | null;
+export declare function isPhiRegionSignalAddress(address: string): boolean;
+export declare function isPhiSignalAddress(value: unknown): value is PhiSignalAddress;
+export declare function readPhiSignalAddress(value: unknown): PhiSignalAddress | undefined;
+export declare function isPhiSignalReceiver(value: unknown): value is PhiSignalReceiver;
+/**
+ * Why a receiver may not be addressed in a scope, said in one sentence, or nothing when it may.
+ *
+ * The same sentence twice over until now: phi-server refused these on the way in, the site UI refused
+ * to deliver them at runtime, and neither knew the other's wording. What the two still do differently
+ * is what they do with the answer -- one rejects a write, the other drops a signal.
+ */
+export declare function readPhiSignalReceiverScopeProblem(scope: PhiSignalScope, receiver: PhiSignalReceiver): string | null;

package/dist/signals.js

@@ -10,6 +10,7 @@
  * of widget shapes that belongs to the UI: phi-server checks that a JSON signal names *a* schema, never
  * which one, so the catalogue is not something the two must agree on.
  */
+import { isPhiCmsInstanceId } from "./cms.js";
 export const PHI_SIGNAL_SCOPES = [
     "widget",
     "layout",
@@ -83,3 +84,120 @@ export function isPhiSignalValueSchemaShape(value) {
     const leaf = value.slice(marker + PHI_SIGNAL_VALUE_SCHEMA_NAMESPACE.length + PHI_SIGNAL_VALUE_SCHEMA_SEPARATOR.length * 2);
     return leaf.length > 0 && !leaf.includes(PHI_SIGNAL_VALUE_SCHEMA_SEPARATOR);
 }
+/**
+ * Whether a string can name an npm package.
+ *
+ * The lexical rule the controller address family starts from, and the one phi-server had copied under
+ * a different name to validate the same addresses. It is the same test `@phis/ui` keeps beside its own
+ * package name for the grammars that do not travel -- module ids, module-scoped keys. If a second
+ * grammar in this package needs it, that is the moment to give it a subpath of its own.
+ */
+export function isPhiNpmPackageName(value) {
+    if (!value || value.includes(":") || value.length > 214) {
+        return false;
+    }
+    return value.startsWith("@")
+        ? /^@[a-z0-9][a-z0-9._~-]*\/[a-z0-9][a-z0-9._~-]*$/.test(value)
+        : /^[a-z0-9][a-z0-9._~-]*$/.test(value);
+}
+/**
+ * The one address the Site scope privileges.
+ *
+ * Site-scoped signals reach across Areas, so nothing addressable inside one may be named in that scope
+ * -- no CMS instance, no Region, no broadcast. The Core Runtime Controller is the exception, and both
+ * sides have to name the same string for the rule to mean anything. `@phis/ui` builds it from its own
+ * constants and asserts it matches this one.
+ */
+export const PHI_CORE_RUNTIME_CONTROLLER_ADDRESS = "controller:@phis/ui/modules/core/controller/default:default";
+export function isPhiSignalAddressSegment(value) {
+    return value.length > 0 && !value.includes("/") && !value.includes(":");
+}
+/**
+ * A controller lives in the namespace of the Module that owns it, so a plugin key is either a bare
+ * package name or that package followed by `/modules/<module>/<namespace>`. Foreign packages use
+ * either form; the grammar does not privilege first-party keys.
+ */
+export function isPhiControllerPluginKey(value) {
+    const marker = value.indexOf("/modules/");
+    if (marker < 0) {
+        return isPhiNpmPackageName(value);
+    }
+    const rest = value.slice(marker + "/modules/".length).split("/");
+    return (isPhiNpmPackageName(value.slice(0, marker)) &&
+        rest.length === 2 &&
+        rest.every((part) => isPhiSignalAddressSegment(part)));
+}
+export function isPhiControllerSignalAddress(address) {
+    if (typeof address !== "string" || !address.startsWith("controller:")) {
+        return false;
+    }
+    const body = address.slice("controller:".length);
+    const instanceSeparatorIndex = body.lastIndexOf(":");
+    if (instanceSeparatorIndex <= 0 || instanceSeparatorIndex === body.length - 1) {
+        return false;
+    }
+    const namespacedType = body.slice(0, instanceSeparatorIndex);
+    const instanceKey = body.slice(instanceSeparatorIndex + 1);
+    const controllerSeparatorIndex = namespacedType.lastIndexOf("/");
+    if (controllerSeparatorIndex <= 0 || controllerSeparatorIndex === namespacedType.length - 1) {
+        return false;
+    }
+    return (isPhiControllerPluginKey(namespacedType.slice(0, controllerSeparatorIndex)) &&
+        isPhiSignalAddressSegment(namespacedType.slice(controllerSeparatorIndex + 1)) &&
+        isPhiSignalAddressSegment(instanceKey));
+}
+/** The instance a `cms:` address names, or null when the string is not one. */
+export function readPhiCmsSignalAddressInstanceId(address) {
+    if (!address.startsWith("cms:")) {
+        return null;
+    }
+    const parts = address.slice("cms:".length).split(":");
+    if ((parts.length !== 1 && parts.length !== 2) ||
+        !isPhiCmsInstanceId(parts[0]) ||
+        (parts.length === 2 && !isPhiSignalAddressSegment(parts[1]))) {
+        return null;
+    }
+    return parts[0];
+}
+export function isPhiRegionSignalAddress(address) {
+    return address.startsWith("region:") && isPhiSignalAddressSegment(address.slice("region:".length));
+}
+export function isPhiSignalAddress(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    const address = value.trim();
+    return readPhiCmsSignalAddressInstanceId(address) != null ||
+        isPhiRegionSignalAddress(address) ||
+        isPhiControllerSignalAddress(address);
+}
+export function readPhiSignalAddress(value) {
+    return isPhiSignalAddress(value) ? value.trim() : undefined;
+}
+export function isPhiSignalReceiver(value) {
+    return value === null || value === "broadcast" || isPhiSignalAddress(value);
+}
+/**
+ * Why a receiver may not be addressed in a scope, said in one sentence, or nothing when it may.
+ *
+ * The same sentence twice over until now: phi-server refused these on the way in, the site UI refused
+ * to deliver them at runtime, and neither knew the other's wording. What the two still do differently
+ * is what they do with the answer -- one rejects a write, the other drops a signal.
+ */
+export function readPhiSignalReceiverScopeProblem(scope, receiver) {
+    if (scope !== "site" || receiver === null) {
+        return null;
+    }
+    if (receiver === "broadcast") {
+        return "must not broadcast in Site scope";
+    }
+    if (readPhiCmsSignalAddressInstanceId(receiver) != null) {
+        return "must not target a CMS instance in Site scope";
+    }
+    if (isPhiRegionSignalAddress(receiver)) {
+        return "must not target a Region in Site scope";
+    }
+    return receiver === PHI_CORE_RUNTIME_CONTROLLER_ADDRESS
+        ? null
+        : "may target only the Core Runtime Controller in Site scope";
+}

package/dist/site-groups.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The membership ladder of a Site group, as both ends must count it.
+ *
+ * These numbers cross the wire. A membership row is written by `PATCH .../members/<userId>` carrying
+ * `membershipFlags` as an integer, and the administration surface offers the levels to choose from, so
+ * the site UI does arithmetic on the same bits phis stores. (The Add-on boundary is the other case:
+ * there a level crosses by name, as `PHIS_GROUP_LEVELS`, because an Add-on has no reason to
+ * know the bits at all.)
+ *
+ * They were declared on both sides and had drifted, which cost a level. phis counts four --
+ * `GROUPS_AND_STORAGE.md` enforces `Manager => Editor => Author => Member` -- and the UI counted
+ * three, calling `1|2` a Contributor and `1|2|4` a Manager. So the UI's Manager was phis's Editor:
+ * granting it left out the bit that administers membership and deletes what others made, and the
+ * viewer was shown a level they did not have. An actual Manager, at `1|2|4|8`, the UI could not name.
+ *
+ * The levels are cumulative, and that is the point of the ordering rather than an implementation
+ * detail: "may edit only their own" is a narrowing of "may edit", so an Author sits below an Editor
+ * on one ladder rather than beside them on another.
+ */
+export declare const PhiGroupMembershipFlags: {
+    /** Reads what the group holds. */
+    readonly Member: 1;
+    /** Creates, and may edit and delete what they created. */
+    readonly Author: number;
+    /** Reaches what others created. */
+    readonly Editor: number;
+    /** Deletes what anyone created, and administers the group's membership. */
+    readonly Manager: number;
+};
+export type PhiGroupMembershipFlagValue = (typeof PhiGroupMembershipFlags)[keyof typeof PhiGroupMembershipFlags];
+/** Ascending, so a selector offers them in the order they widen. */
+export declare const PHI_GROUP_MEMBERSHIP_LEVELS: readonly [1, number, number, number];
+/**
+ * The level a stored value amounts to, highest bit first, or `null` if it is not one.
+ *
+ * Reading downwards is what makes an unknown higher bit fail closed rather than round up.
+ */
+export declare function readPhiGroupMembershipLevel(value: unknown): PhiGroupMembershipFlagValue | null;

package/dist/site-groups.js

@@ -0,0 +1,54 @@
+/**
+ * The membership ladder of a Site group, as both ends must count it.
+ *
+ * These numbers cross the wire. A membership row is written by `PATCH .../members/<userId>` carrying
+ * `membershipFlags` as an integer, and the administration surface offers the levels to choose from, so
+ * the site UI does arithmetic on the same bits phis stores. (The Add-on boundary is the other case:
+ * there a level crosses by name, as `PHIS_GROUP_LEVELS`, because an Add-on has no reason to
+ * know the bits at all.)
+ *
+ * They were declared on both sides and had drifted, which cost a level. phis counts four --
+ * `GROUPS_AND_STORAGE.md` enforces `Manager => Editor => Author => Member` -- and the UI counted
+ * three, calling `1|2` a Contributor and `1|2|4` a Manager. So the UI's Manager was phis's Editor:
+ * granting it left out the bit that administers membership and deletes what others made, and the
+ * viewer was shown a level they did not have. An actual Manager, at `1|2|4|8`, the UI could not name.
+ *
+ * The levels are cumulative, and that is the point of the ordering rather than an implementation
+ * detail: "may edit only their own" is a narrowing of "may edit", so an Author sits below an Editor
+ * on one ladder rather than beside them on another.
+ */
+export const PhiGroupMembershipFlags = {
+    /** Reads what the group holds. */
+    Member: 1,
+    /** Creates, and may edit and delete what they created. */
+    Author: 1 | 2,
+    /** Reaches what others created. */
+    Editor: 1 | 2 | 4,
+    /** Deletes what anyone created, and administers the group's membership. */
+    Manager: 1 | 2 | 4 | 8,
+};
+/** Ascending, so a selector offers them in the order they widen. */
+export const PHI_GROUP_MEMBERSHIP_LEVELS = [
+    PhiGroupMembershipFlags.Member,
+    PhiGroupMembershipFlags.Author,
+    PhiGroupMembershipFlags.Editor,
+    PhiGroupMembershipFlags.Manager,
+];
+/**
+ * The level a stored value amounts to, highest bit first, or `null` if it is not one.
+ *
+ * Reading downwards is what makes an unknown higher bit fail closed rather than round up.
+ */
+export function readPhiGroupMembershipLevel(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0)
+        return null;
+    if (value > PhiGroupMembershipFlags.Manager)
+        return null;
+    if ((value & 8) !== 0)
+        return PhiGroupMembershipFlags.Manager;
+    if ((value & 4) !== 0)
+        return PhiGroupMembershipFlags.Editor;
+    if ((value & 2) !== 0)
+        return PhiGroupMembershipFlags.Author;
+    return PhiGroupMembershipFlags.Member;
+}