@phis/contracts 0.2.0 → 0.4.0

package/dist/capabilities.d.ts

@@ -11,7 +11,12 @@
  * are absent rather than throwing: an Add-on that reaches for one it did not declare finds `undefined`
  * at the point where it made the mistake.
  */
-import type { PhiServerDataCapabilityV1 } from "./queries.js";
+import type { PhisAssetsCapabilityV1 } from "./assets.js";
+import type { PhisAddonEventId } from "./core.js";
+import type { PhisDataCapabilityV1 } from "./queries.js";
+import type { PhisResourceLinksCapabilityV1 } from "./resource-links.js";
+import type { PhisSupportCapabilityV1 } from "./support.js";
+import type { PhisThreadsCapabilityV1 } from "./threads.js";
 /**
  * The cumulative group levels, by name.
  *
@@ -19,22 +24,22 @@ import type { PhiServerDataCapabilityV1 } from "./queries.js";
  * to do arithmetic on them, and a value that never leaves Core is one an Add-on cannot come to depend
  * on. Each level does everything the one before it does and one thing more.
  */
-export declare const PHI_SERVER_GROUP_LEVELS: readonly ["member", "author", "editor", "manager"];
-export type PhiServerGroupLevel = (typeof PHI_SERVER_GROUP_LEVELS)[number];
+export declare const PHIS_GROUP_LEVELS: readonly ["member", "author", "editor", "manager"];
+export type PhisGroupLevel = (typeof PHIS_GROUP_LEVELS)[number];
 /**
  * What an actor wants to do to one row.
  *
  * Creating is absent on purpose. There is no row to ask about yet, and whether an Add-on may write at
  * all is settled before its handler runs.
  */
-export type PhiServerRowIntent = "read" | "update" | "delete";
+export type PhisRowIntent = "read" | "update" | "delete";
 /**
  * A Site capability an Add-on may ask after, named symbolically.
  *
  * An Add-on never states a role flag. Which capabilities are askable is then a decision, and Core is
  * free to change what a role means without an installed Add-on holding a stale bitmask.
  */
-export declare const PHI_SERVER_SITE_ACCESS: {
+export declare const PHIS_SITE_ACCESS: {
     readonly siteAdmin: "site-admin";
     readonly developerTools: "developer-tools";
     readonly structureAuthoring: "structure-authoring";
@@ -44,7 +49,7 @@ export declare const PHI_SERVER_SITE_ACCESS: {
     readonly support: "support";
     readonly accounting: "accounting";
 };
-export type PhiServerSiteAccess = (typeof PHI_SERVER_SITE_ACCESS)[keyof typeof PHI_SERVER_SITE_ACCESS];
+export type PhisSiteAccess = (typeof PHIS_SITE_ACCESS)[keyof typeof PHIS_SITE_ACCESS];
 /**
  * The authorization capability: `@phis/server/authorization:v1`.
  *
@@ -60,7 +65,7 @@ export type PhiServerSiteAccess = (typeof PHI_SERVER_SITE_ACCESS)[keyof typeof P
  * A table that is neither owner- nor group-scoped has nothing for this to decide and always answers
  * false: absence of a scope is not absence of a restriction.
  */
-export type PhiServerAuthorizationCapabilityV1 = {
+export type PhisAuthorizationCapabilityV1 = {
     /**
      * Whether the acting user may do this to one row of one of this Add-on's own tables.
      *
@@ -72,12 +77,12 @@ export type PhiServerAuthorizationCapabilityV1 = {
     mayActOnRow(input: {
         table: string;
         id: number | string;
-        intent: PhiServerRowIntent;
+        intent: PhisRowIntent;
     }): Promise<boolean>;
     /** The level the acting user effectively holds in one group, or null when they are not in it. */
-    groupLevel(groupId: number): Promise<PhiServerGroupLevel | null>;
+    groupLevel(groupId: number): Promise<PhisGroupLevel | null>;
     /** Whether the acting user holds one Site capability, with the Core Admin override applied. */
-    hasSiteAccess(access: PhiServerSiteAccess): Promise<boolean>;
+    hasSiteAccess(access: PhisSiteAccess): Promise<boolean>;
 };
 /**
  * The capabilities a handler may find on its context, keyed as the Core catalog keys them.
@@ -85,14 +90,18 @@ export type PhiServerAuthorizationCapabilityV1 = {
  * Optional throughout: presence follows the manifest, and a capability this release does not offer
  * stops the Add-on at the dispatcher rather than arriving as a broken object.
  */
-export type PhiServerAddonCapabilities = {
-    authorization?: PhiServerAuthorizationCapabilityV1;
-    data?: PhiServerDataCapabilityV1;
-    storage?: PhiServerStorageCapabilityV1;
-    secrets?: PhiServerSecretsCapabilityV1;
-    groups?: PhiServerGroupsCapabilityV1;
-    settings?: PhiServerSettingsCapabilityV1;
-    roles?: PhiServerRolesCapabilityV1;
+export type PhisAddonCapabilities = {
+    authorization?: PhisAuthorizationCapabilityV1;
+    data?: PhisDataCapabilityV1;
+    storage?: PhisStorageCapabilityV1;
+    assets?: PhisAssetsCapabilityV1;
+    secrets?: PhisSecretsCapabilityV1;
+    groups?: PhisGroupsCapabilityV1;
+    threads?: PhisThreadsCapabilityV1;
+    resourceLinks?: PhisResourceLinksCapabilityV1;
+    support?: PhisSupportCapabilityV1;
+    settings?: PhisSettingsCapabilityV1;
+    roles?: PhisRolesCapabilityV1;
 };
 /**
  * The roles capability: `@phis/server/roles:v1`.
@@ -105,7 +114,7 @@ export type PhiServerAddonCapabilities = {
  * handed over, the same way a stored setting nobody declared is not -- so an Add-on never sees a role it
  * does not know, whatever has accumulated across versions.
  */
-export type PhiServerRolesCapabilityV1 = {
+export type PhisRolesCapabilityV1 = {
     /** Whether the acting user holds this role here. False when nobody is acting. */
     has(role: string): Promise<boolean>;
     /** Every declared role the acting user holds, in declaration order. */
@@ -124,18 +133,39 @@ export type PhiServerRolesCapabilityV1 = {
  * Media Space with its folders, quotas and delivery policies. This is for what an Add-on keeps for
  * itself: a release artifact, a generated preview, an export waiting to be fetched.
  */
-export type PhiServerStorageCapabilityV1 = {
+export type PhisStorageCapabilityV1 = {
+    /**
+     * Both directions are streams, because two of the three things this store is for -- a release
+     * artifact and an export waiting to be fetched -- are the things that grow. A buffer would make the
+     * Site's largest allowed object the memory one call costs, on a path that only moves bytes.
+     *
+     * `byteSize` is declared rather than measured. The store's ceiling is booked before a byte is
+     * written, so that a write arriving at the same time as another cannot find room that the other
+     * already took, and nothing can be booked that has not been stated. Core counts while it writes and
+     * refuses a body that turns out not to be the size it claimed, so the declaration is a promise the
+     * Add-on is held to rather than one it is trusted on.
+     *
+     * An Add-on that already holds its bytes wraps them in a one-chunk `ReadableStream` and states
+     * `bytes.byteLength`.
+     */
     put(input: {
         key: string;
-        body: Uint8Array;
+        body: ReadableStream<Uint8Array>;
+        byteSize: number;
         contentType: string;
     }): Promise<{
         key: string;
         byteSize: number;
     }>;
-    /** Null rather than throwing for an object that is not there. */
+    /**
+     * Null rather than throwing for an object that is not there.
+     *
+     * The body arrives as it is read. `byteSize` comes with it so a caller that does need every byte can
+     * decide before it starts collecting them.
+     */
     get(key: string): Promise<{
-        body: Uint8Array;
+        body: ReadableStream<Uint8Array>;
+        byteSize: number;
         contentType: string;
     } | null>;
     head(key: string): Promise<{
@@ -147,6 +177,23 @@ export type PhiServerStorageCapabilityV1 = {
     remove(key: string): Promise<boolean>;
     /** The Add-on's own keys under a prefix, relative as they were given. */
     list(prefix?: string): Promise<string[]>;
+    /**
+     * What this Add-on holds on this Site, and what it is allowed to hold.
+     *
+     * The ceilings are the operator's and are enforced by Core: a `put` past one is refused whether or
+     * not anybody read this first. It is here so an Add-on can say *why* -- a refusal an interface can
+     * explain before it happens beats one that arrives as an error, and a vendor who can see they are at
+     * their limit does not file a bug about it.
+     *
+     * `null` means no ceiling. Both counts are kept as running totals rather than counted on demand,
+     * because counting would mean listing the store -- the unbounded read the ceiling exists to prevent.
+     */
+    usage(): Promise<{
+        bytes: number;
+        objects: number;
+        quotaBytes: number | null;
+        quotaObjects: number | null;
+    }>;
 };
 /**
  * The secrets capability: `@phis/server/secrets:v1`.
@@ -158,7 +205,7 @@ export type PhiServerStorageCapabilityV1 = {
  * There is no writer. An operator sets a secret with `phis secret set`; a package that could write its
  * own would be a package that could plant one.
  */
-export type PhiServerSecretsCapabilityV1 = {
+export type PhisSecretsCapabilityV1 = {
     /** The value, or null when the operator has not configured it. */
     read(name: string): Promise<string | null>;
 };
@@ -168,7 +215,7 @@ export type PhiServerSecretsCapabilityV1 = {
  * Deliberately the same projection one group member gets of another: a display name, a company only
  * where the group discloses it, and never an address. An Add-on renders "listed by" and nothing more.
  */
-export type PhiServerUserProjection = {
+export type PhisUserProjection = {
     userId: number;
     displayName: string | null;
     companyName: string | null;
@@ -182,22 +229,87 @@ export type PhiServerUserProjection = {
  * its actor could already see in them. It cannot become a directory of a Site's users, because there is
  * no question here that reaches past the actor's own membership.
  */
-export type PhiServerGroupsCapabilityV1 = {
-    /** The groups the acting user belongs to on this Site. */
+export type PhisGroupsCapabilityV1 = {
+    /**
+     * The groups this Add-on declared, on this Site, with the ids Core gave them.
+     *
+     * The one answer here that is not about the acting user, and it does not have to be: these are the
+     * Add-on's own groups, created because its manifest asked for them. It needs the id to write a
+     * group-scoped row, and there is no other way to learn one -- a key is what the manifest states, an
+     * id is what the database assigns. An unauthenticated hook may ask, because the answer says nothing
+     * about anybody.
+     */
+    declared(): Promise<Array<{
+        id: number;
+        key: string;
+        name: string;
+    }>>;
+    /**
+     * The groups the acting user belongs to on this Site, and how far into each one they stand.
+     *
+     * The level is here because an Add-on that administers its own groups has to be able to ask "is this
+     * person a Manager of *this* group" -- Core's own check is per Add-on and cannot answer it. Without
+     * it, an Add-on whose policy admits its vendors would let any of them into any of its groups.
+     */
     myGroups(): Promise<Array<{
         id: number;
         key: string;
         name: string;
+        level: PhisGroupLevel;
     }>>;
     /** The members of one group the acting user is in, projected as a member sees them. */
-    members(groupId: number): Promise<PhiServerUserProjection[]>;
+    members(groupId: number): Promise<PhisUserProjection[]>;
     /**
      * One person, if the acting user shares a group with them.
      *
      * Null otherwise, and null is the whole point: it is what stops a row's owner id from becoming a
      * lookup into everybody.
      */
-    user(userId: number): Promise<PhiServerUserProjection | null>;
+    user(userId: number): Promise<PhisUserProjection | null>;
+    /**
+     * Makes a group of this Add-on's own, or hands back the one that is already there.
+     *
+     * Only where the manifest declares a `groupWriter`, and only for an acting user its policy admits.
+     * Asking twice is the way to learn an id: the key is the Add-on's to choose and the id is the
+     * database's to assign, so the call is an upsert rather than a create that fails the second time.
+     *
+     * The group carries this Add-on as its provider, which is what every write below checks. Core already
+     * filters group claims against the available providers, so one of these stops granting anything the
+     * moment the Add-on is gone -- and comes back with it, members included.
+     */
+    create(input: {
+        key: string;
+        name: string;
+    }): Promise<{
+        id: number;
+        key: string;
+        name: string;
+    }>;
+    /**
+     * Puts somebody in one of this Add-on's groups, at one level.
+     *
+     * Refused for a group this Add-on does not own, and for somebody who is not a member of the Site --
+     * a row owned by an account that cannot sign in here is a row nobody can reach.
+     */
+    addMember(input: {
+        groupId: number;
+        userId: number;
+        level: PhisGroupLevel;
+    }): Promise<boolean>;
+    /** Takes somebody out again. False where there was nothing to take out. */
+    removeMember(input: {
+        groupId: number;
+        userId: number;
+    }): Promise<boolean>;
+    /**
+     * Retires one of this Add-on's groups.
+     *
+     * Not deleting: the row and its key stay, because access policies are serialized against the
+     * provider-qualified key and releasing it would let a later group of the same name inherit them.
+     */
+    retire(input: {
+        groupId: number;
+    }): Promise<boolean>;
 };
 /**
  * The settings capability: `@phis/server/settings:v1`.
@@ -212,7 +324,7 @@ export type PhiServerGroupsCapabilityV1 = {
  * A setting the operator has not set answers with the declared default, so an Add-on has one shape to
  * handle rather than two, and `null` means genuinely unset with no default to fall back to.
  */
-export type PhiServerSettingsCapabilityV1 = {
+export type PhisSettingsCapabilityV1 = {
     read(name: string): Promise<string | number | boolean | null>;
     all(): Promise<Readonly<Record<string, string | number | boolean | null>>>;
 };
@@ -224,7 +336,7 @@ export type PhiServerSettingsCapabilityV1 = {
  * 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.
  */
-export type PhiServerAddonJobContext = {
+export type PhisAddonJobContext = {
     addonId: string;
     jobId: string;
     /** This run, for correlating what the job logs with what the operator started. */
@@ -234,7 +346,37 @@ export type PhiServerAddonJobContext = {
         id: number;
         key: string;
     };
-    capabilities: PhiServerAddonCapabilities;
+    capabilities: PhisAddonCapabilities;
+    signal: AbortSignal;
+};
+/**
+ * One event Core hands an Add-on after the fact.
+ *
+ * A handler runs with no actor -- nobody called it, something happened -- and reaches exactly what the
+ * link that caused the delivery reaches. It is the counterpart of a hook: a hook is the outside telling
+ * 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.
+ */
+export type PhisAddonEventContext = {
+    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;
 };
-export type PhiServerAddonJobHandler = (context: PhiServerAddonJobContext) => Promise<void> | void;
+export type PhisAddonEventHandler = (context: PhisAddonEventContext) => Promise<void> | void;
+export type PhisAddonJobHandler = (context: PhisAddonJobContext) => Promise<void> | void;

package/dist/capabilities.js

@@ -18,14 +18,14 @@
  * to do arithmetic on them, and a value that never leaves Core is one an Add-on cannot come to depend
  * on. Each level does everything the one before it does and one thing more.
  */
-export const PHI_SERVER_GROUP_LEVELS = ["member", "author", "editor", "manager"];
+export const PHIS_GROUP_LEVELS = ["member", "author", "editor", "manager"];
 /**
  * A Site capability an Add-on may ask after, named symbolically.
  *
  * An Add-on never states a role flag. Which capabilities are askable is then a decision, and Core is
  * free to change what a role means without an installed Add-on holding a stale bitmask.
  */
-export const PHI_SERVER_SITE_ACCESS = {
+export const PHIS_SITE_ACCESS = {
     siteAdmin: "site-admin",
     developerTools: "developer-tools",
     structureAuthoring: "structure-authoring",

package/dist/catalog.d.ts

@@ -0,0 +1,104 @@
+/**
+ * What a Module is for, as an operator reads it on the Modules page.
+ *
+ * An Add-on declares it, per Module and not per package, because a package may ship a shop and a
+ * report and neither answer would be true of the other. The site UI groups the Modules page by it, and
+ * a Module may read another's category and show it.
+ *
+ * Here rather than in the site UI package because of the reader that cannot follow it there: a
+ * marketplace is a phi-server Add-on, it compiles against this package and nothing else, and it is
+ * meant to let a shopper filter on category. That filter is not built yet -- the offering's category is
+ * still free text -- but it is the reason this list is a contract and not a UI detail.
+ *
+ * Deliberately not in `/addon`. That subpath is the frozen ABI a third party compiles against, and this
+ * list grows as the product does: an eighth category would lift the package everybody builds against,
+ * for a change that concerns none of them. phi-server never asks the membership question either -- a
+ * package manifest carries its Modules' categories as plain strings, Core checks the shape, and the
+ * stricter question is asked where a registry is actually held. That is the same split `/signals`
+ * makes, for the same reason.
+ *
+ * A closed list rather than free text, because free text produced a bijection: every one of the
+ * eighteen built-in Modules answered the field with its own name, so the column repeated the title it
+ * stood next to and no Add-on could have guessed a value another Module already used. An Add-on that
+ * fits nothing here says `other` rather than inventing a nineteenth.
+ *
+ * Several values claim no built-in at all, and that is deliberate. A vocabulary that only describes
+ * what already exists is right for an internal registry and wrong for a market: the shelf has to be
+ * there before the goods, or the first arrival is filed under `other` and nobody ever finds it. So
+ * this list is read as a question about what a Module is for, not as an index of what we happen to
+ * have built.
+ *
+ * An Area's base Module is `foundation` whatever the Area does, because it is not a Module the
+ * operator chose -- it is the ground the Area stands on, and the row for it is the locked one. So is a
+ * Module no site can sensibly do without: locales, logs, revisions, the theme, the user table. Those
+ * are switchable and the base Modules are not, but the question the category answers is what a Module
+ * is for, not whether it can be turned off -- and the answer for all of them is the same: they are what
+ * a site is administered with, not something it was extended by.
+ *
+ * Distinct from the plugin categories the site UI keeps, which file a Widget or Layout into a drawer of
+ * the Builder's insert picker. That is a question about where a block is found, not about what a Module
+ * is, and it is answered by the UI alone.
+ */
+export declare const PHI_RUNTIME_MODULE_CATEGORIES: readonly ["foundation", "workspace", "content", "media", "commerce", "identity", "communication", "events", "analytics", "integration", "operations", "other"];
+export type PhiRuntimeModuleCategory = (typeof PHI_RUNTIME_MODULE_CATEGORIES)[number];
+export declare function isPhiRuntimeModuleCategory(value: unknown): value is PhiRuntimeModuleCategory;
+/**
+ * The category to file a Module under, for a reader that did not compile against this list.
+ *
+ * A separately shipped Add-on may name a category added after the site it is installed on was built.
+ * Refusing it would cost the operator the whole Modules page over one unknown word, so an unrecognised
+ * category reads as `other` -- which is what an Add-on that fits nothing is meant to say anyway.
+ *
+ * A Module built in the same tree never reaches this: its category is typed, so a typo is a compile
+ * error long before anything renders. This is for the values that arrive already compiled.
+ */
+export declare function readPhiRuntimeModuleCategory(value: unknown): PhiRuntimeModuleCategory;
+/** The package.json key a Module package declares itself under. */
+export declare const PHIS_MODULE_PACKAGE_KEY: "phis";
+/** One Module a package contributes, as its package.json states it. */
+export type PhisModulePackageEntry = {
+    moduleId: string;
+    /**
+     * Shape, not membership. A category this build has never heard of is still a well-formed
+     * declaration; whether it is a category *we* offer is the question a party with the list asks, and
+     * asks at intake, where refusing costs the publisher a message rather than the operator a page.
+     */
+    category: string;
+};
+/**
+ * What a Module package says about itself, without being run.
+ *
+ * A Module is compiled UI code: React, the Site's bundler, four fixed entry points. Reading a category
+ * out of it means executing a stranger's package inside whatever process asked -- the `phis` CLI, or a
+ * marketplace taking a submission. Neither should, so the package states it instead, in the one file it
+ * already has and that a registry serves without anybody fetching a tarball.
+ *
+ * Not a second manifest. A package carries one product at one version: the Add-on manifest is what
+ * phi-server is handed when an artifact is installed, and this is what a catalogue reads about the half
+ * that never reaches phi-server at all. Same package, same version, different readers.
+ *
+ * Written by the author, like every other field in that file, and their responsibility to keep true to
+ * their own Modules. Nothing compares the two automatically: `phis module` can say whether the entries
+ * are there and well formed, but whether `events` is the right answer for that Module is a judgement
+ * only the author holds. A package that says nothing here, or says it wrongly, is refused by a
+ * marketplace rather than listed on a guess.
+ */
+export type PhisModulePackageDeclaration = {
+    /**
+     * The language the Modules' own titles and descriptions are written in. Null means `en`.
+     *
+     * Per package rather than per Module: one package carries one product, written by one hand. A
+     * catalogue that translates has to know what it is translating from -- told the wrong source it does
+     * not fail, it produces fluent nonsense, which is the one kind of wrong nobody sees.
+     */
+    sourceLocale: string | null;
+    modules: PhisModulePackageEntry[];
+};
+/**
+ * Reads the declaration out of a parsed package.json.
+ *
+ * Null when the key is absent, which is a legitimate answer: a storage adapter is an Add-on and nothing
+ * else, and has no Module half to describe. Present but malformed throws, because that is an author's
+ * mistake and silence would file it next to the honest absence.
+ */
+export declare function readPhisModulePackageDeclaration(packageJson: unknown): PhisModulePackageDeclaration | null;

package/dist/catalog.js

@@ -0,0 +1,116 @@
+/**
+ * What a Module is for, as an operator reads it on the Modules page.
+ *
+ * An Add-on declares it, per Module and not per package, because a package may ship a shop and a
+ * report and neither answer would be true of the other. The site UI groups the Modules page by it, and
+ * a Module may read another's category and show it.
+ *
+ * Here rather than in the site UI package because of the reader that cannot follow it there: a
+ * marketplace is a phi-server Add-on, it compiles against this package and nothing else, and it is
+ * meant to let a shopper filter on category. That filter is not built yet -- the offering's category is
+ * still free text -- but it is the reason this list is a contract and not a UI detail.
+ *
+ * Deliberately not in `/addon`. That subpath is the frozen ABI a third party compiles against, and this
+ * list grows as the product does: an eighth category would lift the package everybody builds against,
+ * for a change that concerns none of them. phi-server never asks the membership question either -- a
+ * package manifest carries its Modules' categories as plain strings, Core checks the shape, and the
+ * stricter question is asked where a registry is actually held. That is the same split `/signals`
+ * makes, for the same reason.
+ *
+ * A closed list rather than free text, because free text produced a bijection: every one of the
+ * eighteen built-in Modules answered the field with its own name, so the column repeated the title it
+ * stood next to and no Add-on could have guessed a value another Module already used. An Add-on that
+ * fits nothing here says `other` rather than inventing a nineteenth.
+ *
+ * Several values claim no built-in at all, and that is deliberate. A vocabulary that only describes
+ * what already exists is right for an internal registry and wrong for a market: the shelf has to be
+ * there before the goods, or the first arrival is filed under `other` and nobody ever finds it. So
+ * this list is read as a question about what a Module is for, not as an index of what we happen to
+ * have built.
+ *
+ * An Area's base Module is `foundation` whatever the Area does, because it is not a Module the
+ * operator chose -- it is the ground the Area stands on, and the row for it is the locked one. So is a
+ * Module no site can sensibly do without: locales, logs, revisions, the theme, the user table. Those
+ * are switchable and the base Modules are not, but the question the category answers is what a Module
+ * is for, not whether it can be turned off -- and the answer for all of them is the same: they are what
+ * a site is administered with, not something it was extended by.
+ *
+ * Distinct from the plugin categories the site UI keeps, which file a Widget or Layout into a drawer of
+ * the Builder's insert picker. That is a question about where a block is found, not about what a Module
+ * is, and it is answered by the UI alone.
+ */
+export const PHI_RUNTIME_MODULE_CATEGORIES = [
+    "foundation",
+    "workspace",
+    "content",
+    "media",
+    "commerce",
+    "identity",
+    "communication",
+    "events",
+    "analytics",
+    "integration",
+    "operations",
+    "other",
+];
+const PHI_RUNTIME_MODULE_CATEGORY_SET = new Set(PHI_RUNTIME_MODULE_CATEGORIES);
+export function isPhiRuntimeModuleCategory(value) {
+    return typeof value === "string" && PHI_RUNTIME_MODULE_CATEGORY_SET.has(value);
+}
+/**
+ * The category to file a Module under, for a reader that did not compile against this list.
+ *
+ * A separately shipped Add-on may name a category added after the site it is installed on was built.
+ * Refusing it would cost the operator the whole Modules page over one unknown word, so an unrecognised
+ * category reads as `other` -- which is what an Add-on that fits nothing is meant to say anyway.
+ *
+ * A Module built in the same tree never reaches this: its category is typed, so a typo is a compile
+ * error long before anything renders. This is for the values that arrive already compiled.
+ */
+export function readPhiRuntimeModuleCategory(value) {
+    return isPhiRuntimeModuleCategory(value) ? value : "other";
+}
+/** The package.json key a Module package declares itself under. */
+export const PHIS_MODULE_PACKAGE_KEY = "phis";
+/**
+ * Reads the declaration out of a parsed package.json.
+ *
+ * Null when the key is absent, which is a legitimate answer: a storage adapter is an Add-on and nothing
+ * else, and has no Module half to describe. Present but malformed throws, because that is an author's
+ * mistake and silence would file it next to the honest absence.
+ */
+export function readPhisModulePackageDeclaration(packageJson) {
+    if (typeof packageJson !== "object" || packageJson === null) {
+        return null;
+    }
+    const declared = packageJson[PHIS_MODULE_PACKAGE_KEY];
+    if (declared === undefined) {
+        return null;
+    }
+    if (typeof declared !== "object" || declared === null || Array.isArray(declared)) {
+        throw new Error(`"${PHIS_MODULE_PACKAGE_KEY}" in package.json must be an object.`);
+    }
+    const block = declared;
+    const sourceLocale = block.sourceLocale;
+    if (sourceLocale !== undefined && (typeof sourceLocale !== "string" || !sourceLocale.trim())) {
+        throw new Error(`"${PHIS_MODULE_PACKAGE_KEY}.sourceLocale" must be a non-empty string when stated.`);
+    }
+    if (!Array.isArray(block.modules)) {
+        throw new Error(`"${PHIS_MODULE_PACKAGE_KEY}.modules" must be an array.`);
+    }
+    const modules = block.modules.map((entry, index) => {
+        const at = `${PHIS_MODULE_PACKAGE_KEY}.modules[${index}]`;
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            throw new Error(`"${at}" must be an object.`);
+        }
+        const { moduleId, category } = 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 };
+    });
+    return { sourceLocale: typeof sourceLocale === "string" ? sourceLocale : null, modules };
+}