@phis/contracts 0.2.0 → 0.3.1

package/README.md

@@ -1,12 +1,14 @@
 # @phis/contracts
 
-The agreements phi-server keeps with what surrounds it. Two of them, under two subpaths, because
-they hold between different parties and freeze at different moments.
+The agreements phi-server keeps with what surrounds it. Each under its own subpath, because they hold
+between different parties and freeze at different moments.
 
 ```
 @phis/contracts/addon     what phi-server and a separately shipped Add-on promise each other
 @phis/contracts/access    the authorization vocabulary phi-server and @phis/ui both evaluate
-@phis/contracts/signals   the signal vocabulary the UI declares against and phi-server validates
+@phis/contracts/signals   the signal vocabulary and address grammar the UI declares in, phi-server validates
+@phis/contracts/catalog   the Module category an Add-on declares, the UI groups by, a market will filter on
+@phis/contracts/cms       the CMS node identity both sides derive, and must derive alike
 ```
 
 There is deliberately no root export. A package you can import from the top invites everything that
@@ -45,6 +47,24 @@ looked wrong on its own, which is why it went unnoticed.
 Each side keeps its own viewer type and passes a projection onto `PhiAccessSubject`, so neither
 package has to adopt the other's shape.
 
+## `/cms`
+
+The encoding of a CMS node's identity: how a Preset node's id is derived from the Module, the preset and
+the node key, and how a draft node's id is derived from the revision it was made in.
+
+This one is not a shape check. It is an arithmetic, and it is here for the opposite of the usual reason:
+not because the two sides ask the same question, but because they must compute the same answer. A Preset
+id is derived rather than allocated, so the site UI can address a node before any row exists and
+phi-server can check that stored wiring points at nodes that are really there.
+
+It stood in two copies until 2026-09-07 -- 170 lines in phi-server, 260 in `@phis/ui`, with
+`hashPresetIdentity` identical line for line. Nothing would have announced a divergence. A changed
+constant on one side produces ids that are still well formed and simply name nothing: Pages stop
+resolving, drafts point at nodes that are not there, and both copies look correct on their own.
+
+The two conveniences built on top stay with `@phis/ui`: the Page-key convention and the map helper are
+its own, and phi-server has no use for either.
+
 ## `/signals`
 
 The closed vocabularies a widget's wiring is written in -- scopes, actions, value types -- and the shape
@@ -55,31 +75,102 @@ the way in. Two lists, one meaning; and when they were two lists they drifted. `
 `date`, `time` and `length`; phi-server had not. A length control's change signal -- from a widget the
 same release shipped -- was refused on save with "valueType is invalid".
 
+The address families are here for a sharper reason than the vocabularies. A wiring is stored by the
+Builder, checked by phi-server on the way in, and delivered by the site UI at runtime, so all three
+parse the same string -- and two of them parsed it from separate copies until 2026-09-07. The server's
+said so in its own comment: it "mirrors the grammar in @phis/ui", because it could not import it. With
+them the rule that says which receivers a scope admits, which had been written out on both sides in
+different words, and the one controller address the Site scope privileges, which is only worth
+anything if both sides name the same string.
+
 Which schemas exist stays with the UI. phi-server checks that a JSON signal names *a* schema, never
 which one, and `isPhiSignalValueSchemaShape` is exactly that much: shape, not membership. The UI asks
 the stricter question, because it holds the module registry; phi-server must not, or it would refuse
 every third party's schema for never having heard of it.
 
+## `/catalog`
+
+What a Module is for, as one closed list: `foundation`, `workspace`, `content`, `commerce`, `people`,
+`operations`, `other`.
+
+An Add-on declares it per Module -- per Module, 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.
+
+It is 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, never against
+React, and it is meant to let a shopper filter on category. That filter is not built yet -- an
+offering's category is still free text -- but it is why this list is a contract.
+
+It is not in `/addon` on purpose. `/addon` 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. Nor does phi-server ask the membership question: a package
+manifest carries its Modules' categories as plain strings, Core checks the shape, and the strict
+question is asked where a registry is actually held. The same split as `/signals`.
+
+The labels an operator reads are not here. Those are label-set keys, translated per site, and they
+belong to the UI; this subpath holds the identifiers the parties spell the same way.
+
+Beside the vocabulary sits the shape a Module package declares itself in, under `phis` in its
+package.json: which Modules it carries, each one's category, and the language their titles and
+descriptions are written in. A Module is compiled UI code, so reading that out of it means executing a
+stranger's package -- inside the `phis` CLI, or inside a marketplace taking a submission. Neither
+should, and a registry serves package.json without anybody fetching a tarball.
+
+It is 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, this is what a catalogue reads about the half that
+never reaches phi-server. Same package, same version, different readers.
+
+The author writes it, as they write every other field in that file. `phis module` can check that the
+entries are present and well formed; whether `events` is the right answer for a given Module is a
+judgement only the author holds. A package that declares nothing, or declares it wrongly, is refused at
+intake rather than listed on a guess.
+
+## `/media`
+
+The words and numbers a Site and phis both have to read the same way about an Asset: the Space kind's
+wire name, the media kinds, the Folder flags, the presentation flags, the image variant keys, and the
+two closed vocabularies that decide deliverability -- `lifecycle_status` and `delivery_policy`.
+
+It is here because the values themselves travel and are then judged on the other side. The site UI
+sends a flag mask as a list filter and an array of flag values when metadata is saved, and phis answers
+the filter with `presentation_flags & mask <> 0` and refuses a value it does not know. An Asset's
+payload carries `lifecycleStatus` and `deliveryPolicy` as the numbers they are in the row, and the UI
+decides from them whether `next/image` may be pointed at the original.
+
+What made it worth moving is what the copies did while nobody looked. Both sides kept their own table,
+and phis still carried `Private`, `Archived` and `Restricted` long after lifecycle and delivery had
+become columns of their own -- so the set of values its metadata route accepted was not the set the UI
+offered. Nothing failed loudly; a drifting copy of a number never does.
+
+The resolvers come with their vocabulary. `normalizePhiMediaKind` and
+`resolvePhiMediaKindFromContentType` are total functions onto the kind list, and a content type that
+lands on `document` in the browser and on `other` on the server files an upload as one thing and lists
+it as another.
+
+What stays outside: how a delivery URL is built, which is each side's own business, and phis's
+`smallint` Space kind, which never reaches a Site -- the wire carries the name instead.
+
 ## What `/addon` covers
 
-- **Manifest** — `PhiServerAddonManifestV1`: identity, version, required core capabilities,
+- **Manifest** — `PhisAddonManifestV1`: identity, version, required core capabilities,
   the routes an Add-on claims, the services it provides.
-- **Runtime** — `PhiServerAddonRuntimeV1`, `PhiServerAddonHandler`,
-  `PhiServerAddonRequestContext`: the shape the artifact's default export must have.
-- **Schema** — `PhiServerAddonSchemaDescriptor` and its column, index, and constraint
+- **Runtime** — `PhisAddonRuntimeV1`, `PhisAddonHandler`,
+  `PhisAddonRequestContext`: the shape the artifact's default export must have.
+- **Schema** — `PhisAddonSchemaDescriptor` and its column, index, and constraint
   descriptors. Tables are declared, not migrated by hand; phi-server applies them.
 - **Service kinds** — the interfaces an Add-on may provide or consume, currently the media
   storage adapter (`PhisMediaStorageAdapter`, upload plans, object I/O).
-- **What Core offers** — `PHI_SERVER_CORE_CAPABILITIES`, the capability ids an Add-on may
-  require; `PHI_SERVER_SERVICE_KINDS`, the service kinds Core owns; and
-  `PHI_SERVER_SERVICE_INTERFACE_DIGESTS`, the digest of each kind's current interface. Declare
+- **What Core offers** — `PHIS_CORE_CAPABILITIES`, the capability ids an Add-on may
+  require; `PHIS_SERVICE_KINDS`, the service kinds Core owns; and
+  `PHIS_SERVICE_INTERFACE_DIGESTS`, the digest of each kind's current interface. Declare
   against these names rather than spelling them out: Core refuses an Add-on whose digest is not
   the one this release offers, and a literal cannot be checked before you ship it.
 
 This list is a promise, not a plan. A capability appears here when Core delivers it, never
 before.
 
-`PHI_SERVER_ADDON_ABI_VERSION` is the single number a server checks an Add-on against.
+`PHIS_ADDON_ABI_VERSION` is the single number a server checks an Add-on against.
 
 ## Admission rule
 
@@ -92,6 +183,15 @@ Into `/access`: only what **phi-server and `@phis/ui` must both evaluate**, beca
 in its own process. Not what both happen to use — a date formatter used on both sides is shared
 convenience, not a contract, and belongs to neither.
 
+Into `/catalog`: only the vocabularies an Add-on **declares a Module in** and another party then reads
+back — closed lists, identifiers only, never the words an operator sees. A vocabulary only the UI ever
+reads stays with the UI.
+
+Into `/media`: only what **crosses the wire as a value and is judged on the other side** — a number
+stored in a column that a request filters on, a name a payload carries. Not a helper both sides happen
+to have written twice: a copy is only a contract when disagreeing about it changes what a request
+returns.
+
 The test for either is the same: name the two parties and the sentence they are promising each
 other. If that sentence cannot be written down, it does not go in here.
 

package/dist/access.d.ts

@@ -30,6 +30,56 @@ export declare const PhiBaseRole: {
     readonly Supporter: number;
     readonly Accountant: number;
 };
+/**
+ * What a stored email address says about itself, as bit flags.
+ *
+ * `user_emails` holds several addresses per account and marks one of them primary. That mark is a flag
+ * rather than its own column because the schema keeps every other such answer in `flags`, and a lone
+ * boolean is the one place a reader has to remember an exception.
+ *
+ * The position is fixed from the first row, and here more strictly than elsewhere: the unique index that
+ * enforces "one primary address per account" is partial on this very bit. Move the bit and the index
+ * silently guards a different question.
+ */
+export declare const PhiUserEmailFlag: {
+    readonly Primary: number;
+};
+/**
+ * Where a stored email address came from.
+ *
+ * The question this answers is asked after the fact and cannot be reconstructed: did this person type
+ * their address themselves, did an administrator set it, or did an identity provider hand it over? An
+ * account that can be created from a command line makes that difference worth keeping.
+ *
+ * Numbers rather than free text, because the set is Core's and a string column accepts every typo as a
+ * new source. Below 20 are Core's own origins; from 20 upward are named providers, and they are named
+ * rather than left to the Add-on that connects them: the Add-on may be replaced, Google will not be.
+ * A provider without a number is `Provider`, and which one it was stands in `user_auth_identities`.
+ *
+ * There is deliberately no `unknown`. Every writer knows why it writes, and a zero default would let
+ * the one that does not pass unnoticed.
+ */
+export declare const PhiUserEmailSource: {
+    readonly Operator: 1;
+    readonly Admin: 2;
+    readonly Registration: 3;
+    readonly Self: 4;
+    readonly Directory: 5;
+    readonly Provider: 9;
+    readonly Google: 20;
+    readonly Apple: 21;
+    readonly Microsoft: 22;
+    readonly GitHub: 23;
+};
+export type PhiUserEmailSourceValue = (typeof PhiUserEmailSource)[keyof typeof PhiUserEmailSource];
+export declare function isPhiUserEmailSource(value: unknown): value is PhiUserEmailSourceValue;
+/**
+ * Which source a login provider's key stands for.
+ *
+ * The mapping lives here because the numbers do: it is this file that says 20 means Google. A key with
+ * no number of its own is `Provider` rather than a guess, and `user_auth_identities` keeps the detail.
+ */
+export declare function phiUserEmailSourceForProvider(providerKey: string): PhiUserEmailSourceValue;
 export type PhiRoleProviderId = `@${string}/${string}`;
 export type PhiGroupProviderId = `@${string}/${string}`;
 export type PhiViewerRoleClaim = {

package/dist/access.js

@@ -30,6 +30,71 @@ export const PhiBaseRole = {
     Supporter: 1 << 5,
     Accountant: 1 << 6,
 };
+/**
+ * What a stored email address says about itself, as bit flags.
+ *
+ * `user_emails` holds several addresses per account and marks one of them primary. That mark is a flag
+ * rather than its own column because the schema keeps every other such answer in `flags`, and a lone
+ * boolean is the one place a reader has to remember an exception.
+ *
+ * The position is fixed from the first row, and here more strictly than elsewhere: the unique index that
+ * enforces "one primary address per account" is partial on this very bit. Move the bit and the index
+ * silently guards a different question.
+ */
+export const PhiUserEmailFlag = {
+    Primary: 1 << 0,
+};
+/**
+ * Where a stored email address came from.
+ *
+ * The question this answers is asked after the fact and cannot be reconstructed: did this person type
+ * their address themselves, did an administrator set it, or did an identity provider hand it over? An
+ * account that can be created from a command line makes that difference worth keeping.
+ *
+ * Numbers rather than free text, because the set is Core's and a string column accepts every typo as a
+ * new source. Below 20 are Core's own origins; from 20 upward are named providers, and they are named
+ * rather than left to the Add-on that connects them: the Add-on may be replaced, Google will not be.
+ * A provider without a number is `Provider`, and which one it was stands in `user_auth_identities`.
+ *
+ * There is deliberately no `unknown`. Every writer knows why it writes, and a zero default would let
+ * the one that does not pass unnoticed.
+ */
+export const PhiUserEmailSource = {
+    Operator: 1,
+    Admin: 2,
+    Registration: 3,
+    Self: 4,
+    Directory: 5,
+    Provider: 9,
+    Google: 20,
+    Apple: 21,
+    Microsoft: 22,
+    GitHub: 23,
+};
+export function isPhiUserEmailSource(value) {
+    return typeof value === "number"
+        && Object.values(PhiUserEmailSource).includes(value);
+}
+/**
+ * Which source a login provider's key stands for.
+ *
+ * The mapping lives here because the numbers do: it is this file that says 20 means Google. A key with
+ * no number of its own is `Provider` rather than a guess, and `user_auth_identities` keeps the detail.
+ */
+export function phiUserEmailSourceForProvider(providerKey) {
+    switch (providerKey.trim().toLowerCase()) {
+        case "google":
+            return PhiUserEmailSource.Google;
+        case "apple":
+            return PhiUserEmailSource.Apple;
+        case "microsoft":
+            return PhiUserEmailSource.Microsoft;
+        case "github":
+            return PhiUserEmailSource.GitHub;
+        default:
+            return PhiUserEmailSource.Provider;
+    }
+}
 /**
  * Flags as they may be trusted.
  *

package/dist/addon-index.d.ts

@@ -1,4 +1,5 @@
 export * from "./addon.js";
+export * from "./assets.js";
 export * from "./capabilities.js";
 export * from "./core.js";
 export * from "./media-storage.js";

package/dist/addon-index.js

@@ -1,4 +1,5 @@
 export * from "./addon.js";
+export * from "./assets.js";
 export * from "./capabilities.js";
 export * from "./core.js";
 export * from "./media-storage.js";

package/dist/addon.d.ts

@@ -11,35 +11,35 @@
  * no node builtins -- the Add-on states, and Core checks. If something here ever does more than hand
  * back a constant, it is in the wrong package.
  */
-import type { PhiServerAddonCapabilities, PhiServerAddonJobHandler, PhiServerSiteAccess } from "./capabilities.js";
-import type { PhiServerCoreCapabilityId, PhiServerServiceKind } from "./core.js";
-import type { PhiServerAddonQueryCatalog } from "./queries.js";
-import type { PhiServerAddonSchemaDescriptor } from "./schema.js";
-export declare const PHI_SERVER_ADDON_MANIFEST_VERSION: 1;
-export declare const PHI_SERVER_ADDON_ABI_VERSION: 1;
-export type PhiServerAddonAuthPolicy = "internal" | "site-user" | "site-admin" | "operator";
-export type PhiServerAddonHttpMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
-export type PhiServerAddonApiRouteDescriptor = {
+import type { PhisAddonCapabilities, PhisAddonJobHandler, PhisSiteAccess } from "./capabilities.js";
+import type { PhisCoreCapabilityId, PhisServiceKind } from "./core.js";
+import type { PhisAddonQueryCatalog } from "./queries.js";
+import type { PhisAddonSchemaDescriptor } from "./schema.js";
+export declare const PHIS_ADDON_MANIFEST_VERSION: 1;
+export declare const PHIS_ADDON_ABI_VERSION: 1;
+export type PhisAddonAuthPolicy = "internal" | "site-user" | "site-admin" | "operator";
+export type PhisAddonHttpMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+export type PhisAddonApiRouteDescriptor = {
     id: string;
-    method: PhiServerAddonHttpMethod;
+    method: PhisAddonHttpMethod;
     path: string;
     handler: string;
-    auth: PhiServerAddonAuthPolicy;
+    auth: PhisAddonAuthPolicy;
     siteScoped: boolean;
     bodyLimitBytes?: number;
     rateLimitClass?: string;
     timeoutMs?: number;
 };
-export type PhiServerAddonHookDescriptor = {
+export type PhisAddonHookDescriptor = {
     id: string;
-    method: PhiServerAddonHttpMethod;
+    method: PhisAddonHttpMethod;
     path: string;
     handler: string;
     bodyLimitBytes: number;
     rateLimitClass: string;
     timeoutMs: number;
     /**
-     * Whether this hook is told which Site it was called for, through `x-phi-site-key`.
+     * Whether this hook is told which Site it was called for, through `x-phis-site-key`.
      *
      * A hook is unauthenticated by construction -- that is what makes it reachable by a payment provider
      * or by somebody else's Core. Without a Site it also has no capabilities at all, because every one of
@@ -50,7 +50,7 @@ export type PhiServerAddonHookDescriptor = {
      */
     siteScoped?: boolean;
 };
-export type PhiServerAddonCapabilityDescriptor = {
+export type PhisAddonCapabilityDescriptor = {
     id: string;
     interfaceDigest: string;
 };
@@ -62,14 +62,14 @@ export type PhiServerAddonCapabilityDescriptor = {
  * reaches the implementation without a dynamic import. The interface digest is checked against what
  * this release offers, so an Add-on built for an older interface is refused rather than called.
  */
-export type PhiServerAddonServiceProviderDescriptor = {
-    serviceKind: PhiServerServiceKind;
+export type PhisAddonServiceProviderDescriptor = {
+    serviceKind: PhisServiceKind;
     providerKey: string;
     interfaceDigest: string;
     factoryExport: string;
-    requiredCoreCapabilities: PhiServerCoreCapabilityId[];
+    requiredCoreCapabilities: PhisCoreCapabilityId[];
 };
-export type PhiServerAddonJobDescriptor = {
+export type PhisAddonJobDescriptor = {
     id: string;
     handler: string;
     /**
@@ -88,7 +88,7 @@ export type PhiServerAddonJobDescriptor = {
  * check a value against its type before it is stored -- the same bargain as the schema and query
  * descriptors, one step smaller.
  */
-export type PhiServerAddonSettingDescriptor = {
+export type PhisAddonSettingDescriptor = {
     name: string;
     type: "text" | "integer" | "boolean";
     /** Shown by the CLI when it lists what an Add-on can be configured with. */
@@ -107,8 +107,8 @@ export type PhiServerAddonSettingDescriptor = {
  * `siteAccess` names one of the Site's own claims; `role` names another role of this same Add-on. A
  * Site Admin may always grant any role of any Add-on, so a graph that reaches nobody still has a way in.
  */
-export type PhiServerAddonRoleGrantPolicy = {
-    siteAccess: PhiServerSiteAccess;
+export type PhisAddonRoleGrantPolicy = {
+    siteAccess: PhisSiteAccess;
 } | {
     role: string;
 };
@@ -122,23 +122,51 @@ export type PhiServerAddonRoleGrantPolicy = {
  * Core never interprets the name. It stores assignments, answers `has()`, and enforces `grantableBy`;
  * what `reviewer` means is the Add-on's business and stays there.
  */
-export type PhiServerAddonRoleDescriptor = {
+export type PhisAddonGroupWriterDescriptor = {
+    /**
+     * Who may cause this Add-on to create a group or change who is in one.
+     *
+     * The same policy shape a role's `grantableBy` uses, evaluated the same way, and with the same floor:
+     * a Site Admin always may, so a badly declared condition never locks a Site out of its own groups.
+     */
+    allowedBy: PhisAddonRoleGrantPolicy;
+};
+export type PhisAddonRoleDescriptor = {
+    name: string;
+    description?: string;
+    grantableBy: PhisAddonRoleGrantPolicy;
+};
+/**
+ * A group this Add-on needs on every Site that runs it.
+ *
+ * Groups are Core's vocabulary about shared rows, so an Add-on cannot invent one at runtime and cannot
+ * put anybody in it -- the groups capability reads and grants nothing. What it can do is say which ones
+ * it needs, and Core creates them per Site when the Site asks for the Add-on. Who is in them stays with
+ * whoever administers the Site, which is the point: a package should not be able to hand out standing.
+ *
+ * The group carries this Add-on's id as its provider, and Core already filters group claims against the
+ * available providers -- so an Add-on's group stops granting anything the moment the Add-on is gone,
+ * without anybody having to remember to clean up.
+ */
+export type PhisAddonGroupDescriptor = {
+    /** Unique within this Add-on. Frozen once a Site has one: memberships point at it by key. */
+    key: string;
+    /** What an administrator sees in the Site's group list. */
     name: string;
     description?: string;
-    grantableBy: PhiServerAddonRoleGrantPolicy;
 };
-export type PhiServerAddonManifestV1 = {
-    manifestVersion: typeof PHI_SERVER_ADDON_MANIFEST_VERSION;
+export type PhisAddonManifestV1 = {
+    manifestVersion: typeof PHIS_ADDON_MANIFEST_VERSION;
     addonId: string;
     packageName: string;
     packageVersion: string;
     serverAbi: string;
-    capabilities: PhiServerAddonCapabilityDescriptor[];
-    serviceProviders: PhiServerAddonServiceProviderDescriptor[];
-    requiredCoreCapabilities: PhiServerCoreCapabilityId[];
-    apiRoutes: PhiServerAddonApiRouteDescriptor[];
-    hooks: PhiServerAddonHookDescriptor[];
-    jobs: PhiServerAddonJobDescriptor[];
+    capabilities: PhisAddonCapabilityDescriptor[];
+    serviceProviders: PhisAddonServiceProviderDescriptor[];
+    requiredCoreCapabilities: PhisCoreCapabilityId[];
+    apiRoutes: PhisAddonApiRouteDescriptor[];
+    hooks: PhisAddonHookDescriptor[];
+    jobs: PhisAddonJobDescriptor[];
     /**
      * What an operator may configure. Absent means nothing is.
      *
@@ -148,7 +176,7 @@ export type PhiServerAddonManifestV1 = {
      * fields may demand an explicit `null`, because no stored manifest predates them; later ones must
      * define what absence means and accept it.
      */
-    settings?: PhiServerAddonSettingDescriptor[];
+    settings?: PhisAddonSettingDescriptor[];
     /**
      * The roles this Add-on defines. Absent means it defines none.
      *
@@ -156,14 +184,50 @@ export type PhiServerAddonManifestV1 = {
      * forgotten it. A name is frozen from the first assignment -- renaming one orphans every grant that
      * points at it, silently, because the grant is stored as text and text does not follow a rename.
      */
-    roles?: PhiServerAddonRoleDescriptor[];
+    roles?: PhisAddonRoleDescriptor[];
+    /**
+     * The groups this Add-on needs. Absent means none.
+     *
+     * Optional like every field added after the manifest version was in the wild, and absent means the
+     * Add-on asks for no group rather than that it forgot to say so.
+     */
+    groups?: PhisAddonGroupDescriptor[];
+    /**
+     * Whether this Add-on may create groups of its own while it runs, and who may cause it to.
+     *
+     * The declared list above is for the groups a Site always has -- one per Add-on, known when the
+     * manifest was written. This is for the ones a Site produces as it runs: one per vendor, per team, per
+     * tenant, whose number and names nobody knew in advance.
+     *
+     * It stays a declaration rather than a capability an Add-on simply has, for the reason `grantableBy`
+     * exists: the manifest is covered by a digest the running code cannot rewrite, so the author states
+     * who may cause a group, and Core decides whether the condition is met. Without it, "an Add-on may
+     * make groups" would mean "an Add-on may make itself an authority container and fill it".
+     *
+     * What it may do is bounded by ownership either way: a group it creates carries its own id as the
+     * provider, and every write here refuses a group carrying anybody else's.
+     */
+    groupWriter?: PhisAddonGroupWriterDescriptor;
+    /**
+     * The Modules this package's other half contributes. Absent means it has no Module half.
+     *
+     * Each id is `<package name>/<module key>`, and the package name is this manifest's own -- one package
+     * carries one product, so there is nothing to resolve. What the field adds is the one thing Core
+     * cannot see from an artifact: whether a Module half exists at all. An Add-on that is only an Add-on,
+     * like a storage provider, says nothing here and is complete on its own.
+     *
+     * It is what lets enabling an Add-on for a Site check that the Site actually has the other half. A
+     * Site with the Add-on and not the Module has routes with no surface: nothing is broken, but an
+     * operator who thinks they switched a feature on finds nothing.
+     */
+    modules?: string[];
     /**
      * The tables this Add-on owns, or null when it owns none.
      *
      * There is no list of migration steps beside it. The descriptor is the desired shape; what has been
      * applied is recorded in the database, and Core derives the difference.
      */
-    schema: PhiServerAddonSchemaDescriptor | null;
+    schema: PhisAddonSchemaDescriptor | null;
     /**
      * The statements this Add-on may run against its own tables, or null when it runs none.
      *
@@ -172,14 +236,14 @@ export type PhiServerAddonManifestV1 = {
      *
      * Optional for the reason `settings` is: it arrived after the manifest version was in the wild.
      */
-    queries?: PhiServerAddonQueryCatalog | null;
+    queries?: PhisAddonQueryCatalog | null;
     /** The version of `schema`, or 0 when there is none. */
     migrationVersion: number;
 };
-export type PhiServerAddonRequestContext = {
+export type PhisAddonRequestContext = {
     addonId: string;
     requestId: string;
-    method: PhiServerAddonHttpMethod;
+    method: PhisAddonHttpMethod;
     url: string;
     headers: Headers;
     body: Uint8Array;
@@ -188,6 +252,15 @@ export type PhiServerAddonRequestContext = {
     site: {
         id: number;
         key: string;
+        /**
+         * Where this Site answers from, as the outside world reaches it.
+         *
+         * Core's own addresses are Site-relative, which is right for a page of that Site and useless in
+         * anything that leaves it: a listing another Core fetches, a link in an email, a picture in a
+         * feed. A handler cannot derive this -- a request carries the host it happened to arrive on, and
+         * an internal one carries none at all -- so it is the Site's own record that says it.
+         */
+        publicBaseUrl: string;
     } | null;
     actor: {
         kind: "operator";
@@ -205,10 +278,10 @@ export type PhiServerAddonRequestContext = {
      * Only what the manifest declared arrives. A capability is not fetched, looked up, or constructed by
      * the Add-on -- it is here or it is not, and it was already decided before the handler ran.
      */
-    capabilities: PhiServerAddonCapabilities;
+    capabilities: PhisAddonCapabilities;
     signal: AbortSignal;
 };
-export type PhiServerAddonHandler = (context: PhiServerAddonRequestContext) => Promise<Response> | Response;
+export type PhisAddonHandler = (context: PhisAddonRequestContext) => Promise<Response> | Response;
 /**
  * A service factory, as the runtime exports it.
  *
@@ -216,24 +289,24 @@ export type PhiServerAddonHandler = (context: PhiServerAddonRequestContext) => P
  * what makes that agreement checkable. The factory receives schema-validated profile configuration and
  * a restricted context, never a database handle or a general secret accessor.
  */
-export type PhiServerAddonServiceFactory = (config: unknown, context: unknown) => unknown;
-export type PhiServerAddonRuntimeV1 = {
-    manifest: PhiServerAddonManifestV1;
-    apiHandlers?: Readonly<Record<string, PhiServerAddonHandler>>;
-    hookHandlers?: Readonly<Record<string, PhiServerAddonHandler>>;
-    serviceFactories?: Readonly<Record<string, PhiServerAddonServiceFactory>>;
-    jobHandlers?: Readonly<Record<string, PhiServerAddonJobHandler>>;
+export type PhisAddonServiceFactory = (config: unknown, context: unknown) => unknown;
+export type PhisAddonRuntimeV1 = {
+    manifest: PhisAddonManifestV1;
+    apiHandlers?: Readonly<Record<string, PhisAddonHandler>>;
+    hookHandlers?: Readonly<Record<string, PhisAddonHandler>>;
+    serviceFactories?: Readonly<Record<string, PhisAddonServiceFactory>>;
+    jobHandlers?: Readonly<Record<string, PhisAddonJobHandler>>;
 };
-export type PhiServerAddonRuntimeModuleV1 = {
-    phiServerAddon: PhiServerAddonRuntimeV1;
+export type PhisAddonRuntimeModuleV1 = {
+    phisAddon: PhisAddonRuntimeV1;
 };
-export type PhiServerAddonBuildEntry = {
+export type PhisAddonBuildEntry = {
     enabled: boolean;
     manifestDigest: string;
-    manifest: PhiServerAddonManifestV1;
-    load: () => Promise<PhiServerAddonRuntimeModuleV1>;
+    manifest: PhisAddonManifestV1;
+    load: () => Promise<PhisAddonRuntimeModuleV1>;
 };
-export type PhiServerAddonBuildManifest = Readonly<Record<string, PhiServerAddonBuildEntry>>;
+export type PhisAddonBuildManifest = Readonly<Record<string, PhisAddonBuildEntry>>;
 /**
  * One installed Add-on, as the operator's desired state records it.
  *
@@ -242,7 +315,7 @@ export type PhiServerAddonBuildManifest = Readonly<Record<string, PhiServerAddon
  * digests bind the three apart: `manifestDigest` covers the descriptors below, `artifactDigest` covers
  * the file in the install root, and the loader refuses a file that no longer matches.
  */
-export type PhiServerAddonDesiredStateEntry = {
+export type PhisAddonDesiredStateEntry = {
     addonId: string;
     packageName: string;
     packageVersion: string;
@@ -250,10 +323,10 @@ export type PhiServerAddonDesiredStateEntry = {
     /** SHA-256 of the installed artifact, and the cache key its load address carries. */
     artifactDigest: string;
     /** The validated descriptors, as read from the artifact at installation. */
-    manifest: PhiServerAddonManifestV1;
+    manifest: PhisAddonManifestV1;
     enabled: boolean;
 };
-export type PhiServerAddonDesiredState = {
+export type PhisAddonDesiredState = {
     formatVersion: 1;
-    addons: PhiServerAddonDesiredStateEntry[];
+    addons: PhisAddonDesiredStateEntry[];
 };

package/dist/addon.js

@@ -11,5 +11,5 @@
  * no node builtins -- the Add-on states, and Core checks. If something here ever does more than hand
  * back a constant, it is in the wrong package.
  */
-export const PHI_SERVER_ADDON_MANIFEST_VERSION = 1;
-export const PHI_SERVER_ADDON_ABI_VERSION = 1;
+export const PHIS_ADDON_MANIFEST_VERSION = 1;
+export const PHIS_ADDON_ABI_VERSION = 1;