@phis/contracts 0.2.0 → 0.3.1

package/dist/assets.d.ts

@@ -0,0 +1,165 @@
+import type { PhiMediaUploadPlan } from "./media-storage.js";
+/**
+ * Files on a row: `@phis/server/assets:v1`.
+ *
+ * The slots are declared in the schema descriptor -- a name, a cardinality, a size ceiling, the media
+ * types it takes, who may fetch it -- and this is how they are filled. An Add-on says which row and
+ * which slot; where the object goes, what it is called and whether it arrived are Core's answers.
+ *
+ * There is one upload lifecycle in Core and this is not a second one. Core reserves, receives, measures
+ * and hashes without knowing who asked; the purpose stated here is read back at the last step, where
+ * the finished object becomes a row in the Add-on's table.
+ *
+ * **No method takes an object key and none returns one.** A key an Add-on chooses is a key Core cannot
+ * recognise later, and an object Core cannot recognise is one it can neither deliver nor account for.
+ * What comes back instead is a Media Asset id, which the delivery Core already has takes.
+ */
+export type PhisAddonAssetView = {
+    id: string;
+    slot: string;
+    ownerId: string;
+    /** The file itself, as Core records it. */
+    mediaAssetId: number;
+    /**
+     * Where the file is served from, Site-relative, as Core addresses its own Media.
+     *
+     * Given rather than left to be composed, because composing it means knowing two things an Add-on has
+     * no way to be told: the route, and the cache revision it carries. A path built without the revision
+     * still delivers the file and never gets an immutable cache -- every viewer revalidates every time,
+     * and nothing about the result looks wrong enough to investigate.
+     *
+     * Read at the moment it is used, never stored. The revision rotates whenever the file's delivery
+     * changes, and a path kept from an earlier read would then be the stale one it exists to retire.
+     *
+     * What the path answers with is the slot's `delivery`: `public` to anyone, `authenticated` to a
+     * session, `internal` only to Core's own caller. The address is not the permission.
+     */
+    contentPath: string;
+    byteSize: number;
+    contentType: string;
+    /**
+     * The digest that was established, with the algorithm that produced it -- or null where none was.
+     *
+     * Established means one of two things: the endpoint verified what the client stated and would have
+     * refused anything else, or Core received the body and hashed it in flight. Null is a truthful "not
+     * established" -- an `etag` is an HTTP header and not a content hash, and a wrong digest here would
+     * be worse than none, because it invites a comparison.
+     *
+     * The algorithm is part of the answer and not an assumption. Which one an endpoint can attest to
+     * differs between Providers, so a bare value would be a number whose meaning the reader has to guess.
+     */
+    checksum: {
+        algorithm: string;
+        value: string;
+    } | null;
+    createdAt: string;
+};
+/**
+ * A place made for a file, and how to deliver it.
+ *
+ * The plan is the Provider's answer, not Core's: an endpoint that can take a body directly says so, and
+ * one that cannot names a Core route to stream through. An Add-on passes it to its client unread.
+ */
+export type PhisAddonAssetReservationView = {
+    /** What the transfer is carried out against, and what `finalize` is called with. */
+    token: string;
+    plan: PhiMediaUploadPlan;
+    expiresAt: string;
+};
+export type PhisAssetsCapabilityV1 = {
+    /**
+     * Reserves a place for a file, before any of it is sent.
+     *
+     * The size is stated now and held to later, and the space is charged now rather than at the end. A
+     * ceiling decided at the end would bound the bookkeeping and not the store: ten clients could each
+     * write a gigabyte and have five of them refused afterwards, with the bytes already paid for.
+     *
+     * `sha256` is the client's statement of what it is about to send. Where the Storage Profile was found
+     * to verify one, it is signed into the plan and the endpoint refuses anything else -- so a wrong
+     * digest never becomes an object, and Core can record the figure as true without having seen a byte.
+     * Where it was not, the body comes through Core and Core hashes it instead.
+     *
+     * Refused where the slot is not declared, where the type is not one it takes, where the size is over
+     * the slot's ceiling or the Site's, where the Space is full, and where the acting user may not change
+     * the row. Attaching a file to a row changes it, so it is the row's authority that decides.
+     */
+    begin(input: {
+        table: string;
+        ownerId: string | number;
+        slot: string;
+        contentType: string;
+        sizeBytes: number;
+        sha256?: string;
+        /** What the file was called where it came from. Core makes one up when there is nothing to use. */
+        filename?: string;
+    }): Promise<PhisAddonAssetReservationView>;
+    /**
+     * Settles a reservation once the bytes are there, and makes the file a row.
+     *
+     * Core looks at what actually landed rather than believing the report: nothing there is not a file,
+     * and a different size than was reserved is not a file either. On a single-valued slot the file being
+     * replaced goes in the same transaction -- there is no moment in which the row holds two.
+     *
+     * Repeating it is safe. A client whose answer was lost cannot tell a finished upload from a failed
+     * one, so a second call answers with the same file rather than with an error.
+     */
+    finalize(input: {
+        table: string;
+        token: string;
+        /** Whatever the plan's issuer asked the client to bring back. Core passes it through unread. */
+        completion?: unknown;
+    }): Promise<PhisAddonAssetView>;
+    /** Gives an unredeemed reservation up. An abandoned one expires on its own; this is the tidy path. */
+    abandon(input: {
+        table: string;
+        token: string;
+    }): Promise<boolean>;
+    /**
+     * The files of a row. A reservation in flight is not among them, because it is not a file yet.
+     *
+     * Refused where the acting user may not read the row. Asking what a row carries is reading the row,
+     * and a slot's `delivery` does not answer it: a file whose id, name and size come back to anyone has
+     * already given up most of what `internal` was keeping.
+     */
+    list(input: {
+        table: string;
+        ownerId: string | number;
+        slot?: string;
+    }): Promise<PhisAddonAssetView[]>;
+    /**
+     * Takes a file out of its slot, and the file with it.
+     *
+     * Refused where the acting user may not change the row, which is the same authority `begin` is
+     * measured against -- taking a file away changes the row exactly as putting one there does. A file
+     * that is not there answers `false` rather than refusing, because a refusal would say it exists.
+     */
+    remove(input: {
+        table: string;
+        id: string;
+    }): Promise<boolean>;
+    /**
+     * What this Add-on's files take up on this Site, and what they are allowed to.
+     *
+     * Here for the reason `storage:v1` has the same call: the ceiling is the operator's and Core enforces
+     * it whether or not anybody read this first, so this exists to let an Add-on say *why*. A refusal an
+     * interface can explain before a person picks a file beats one that arrives after they waited for the
+     * upload, and a vendor who can see they are at their limit does not report it as a fault.
+     *
+     * The two figures are separate because both are spent. `bytes` is what is stored; `reservedBytes` is
+     * held for uploads in flight and is as unavailable as stored bytes until they finish or lapse. Room
+     * for one more file is `quotaBytes - (bytes + reservedBytes)`, which is the comparison `begin` makes.
+     *
+     * `quotaBytes` is the effective ceiling after inheritance -- the Space's own override where there is
+     * one, the Site's default for Add-on Spaces otherwise -- so it is the figure that will actually be
+     * applied and not a raw column. `null` means no ceiling. An explicit `0` is a revocation, not an
+     * absence.
+     *
+     * No object count, unlike `storage:v1`. Core keeps a running total of bytes and none of files, and
+     * counting them on demand would be the unbounded read the ceiling exists to prevent.
+     */
+    usage(): Promise<{
+        bytes: number;
+        reservedBytes: number;
+        quotaBytes: number | null;
+    }>;
+};

package/dist/assets.js

@@ -0,0 +1 @@
+export {};

package/dist/capabilities.d.ts

@@ -11,7 +11,8 @@
  * 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 { PhisDataCapabilityV1 } from "./queries.js";
 /**
  * The cumulative group levels, by name.
  *
@@ -19,22 +20,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 +45,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 +61,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 +73,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 +86,16 @@ 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;
+    settings?: PhisSettingsCapabilityV1;
+    roles?: PhisRolesCapabilityV1;
 };
 /**
  * The roles capability: `@phis/server/roles:v1`.
@@ -105,7 +108,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,7 +127,7 @@ 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 = {
     put(input: {
         key: string;
         body: Uint8Array;
@@ -147,6 +150,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 +178,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 +188,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 +202,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 +297,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 +309,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 +319,97 @@ export type PhiServerAddonJobContext = {
         id: number;
         key: string;
     };
-    capabilities: PhiServerAddonCapabilities;
+    capabilities: PhisAddonCapabilities;
     signal: AbortSignal;
 };
-export type PhiServerAddonJobHandler = (context: PhiServerAddonJobContext) => Promise<void> | void;
+/**
+ * The threads capability: `@phis/server/threads:v1`.
+ *
+ * Core's internal support threads, bounded by the acting user exactly as `groups:v1` is: an Add-on
+ * reads the threads its actor is in and nothing else. A thread is visible to whoever created it, was
+ * named a recipient of it, or stands in a team that was -- there is no listing that steps outside that,
+ * because a Site's threads are its people talking and an Add-on is not a party to them.
+ *
+ * **Without an actor only `create` is offered.** A job and a hook run as the Add-on rather than as a
+ * person, and a person is what thread visibility is made of: an Add-on with no actor is in no thread,
+ * so there is nothing for it to list, read or answer. It may still open one -- naming its recipients as
+ * it goes -- which is what an integration reporting an outside event needs. How such an integration
+ * later appends to the thread it opened is deliberately left unanswered here: it wants a thread the
+ * Add-on owns, and ownership of a thread is a thing to design once something real needs it rather than
+ * to guess at now.
+ */
+export type PhisThreadsCapabilityV1 = {
+    /** The threads the acting user is in, newest activity first. */
+    list(options?: {
+        page?: number;
+        pageSize?: number;
+        unreadOnly?: boolean;
+    }): Promise<PhisThreadSummary[]>;
+    /** One thread with a window of its messages, or null where the actor is not in it. */
+    get(threadId: number, options?: {
+        messageLimit?: number;
+        beforeMessageId?: number | null;
+    }): Promise<PhisThreadDetail | null>;
+    /**
+     * Opens a thread.
+     *
+     * The one call an Add-on may make with no actor behind it. Recipients are named as user ids, team
+     * ids, or both, and every one is checked against this Site before anything is written.
+     */
+    create(input: {
+        subject?: string | null;
+        message: string;
+        messageMarkdown?: string | null;
+        recipientUserIds?: number[];
+        recipientTeamIds?: number[];
+    }): Promise<PhisThreadDetail>;
+    /** Adds a message to a thread the acting user is in. */
+    reply(input: {
+        threadId: number;
+        message: string;
+        messageMarkdown?: string | null;
+    }): Promise<PhisThreadDetail | null>;
+    /** Brings more people into a thread the acting user is in. Adds only; it never removes. */
+    addRecipients(input: {
+        threadId: number;
+        recipientUserIds?: number[];
+        recipientTeamIds?: number[];
+    }): Promise<PhisThreadDetail | null>;
+    /**
+     * Takes a thread out of the active list, for everyone in it.
+     *
+     * One row carries the status, so this is the thread being closed rather than one reader hiding it.
+     */
+    archive(threadId: number): Promise<boolean>;
+    /** Marks the thread read for the acting user, up to its newest message or to one named. */
+    markRead(input: {
+        threadId: number;
+        messageId?: number | null;
+    }): Promise<boolean>;
+};
+export type PhisThreadSummary = {
+    id: number;
+    subject: string | null;
+    status: number;
+    type: number;
+    createdAt: string;
+    updatedAt: string;
+    latestMessageAt: string | null;
+    unread: boolean;
+};
+export type PhisThreadMessage = {
+    id: number;
+    bodyText: string;
+    bodyMarkdown: string | null;
+    author: PhisUserProjection | null;
+    createdAt: string;
+};
+export type PhisThreadDetail = {
+    thread: PhisThreadSummary;
+    messages: PhisThreadMessage[];
+    /** Whether older messages remain beyond the window `messages` carries. */
+    hasMoreMessages: boolean;
+    recipientUserIds: number[];
+    recipientTeamIds: number[];
+};
+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;