@phis/contracts 0.2.0 → 0.4.0

package/NOTICE

@@ -1,4 +1,4 @@
-@phis/addon-contract
+@phis/contracts
 Copyright 2026 Phisys Ltd
 
 This product includes software developed by Phisys Ltd.

package/README.md

@@ -1,102 +1,210 @@
 # @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 phis (`@phis/server`) keeps with what surrounds it: the site UI (`@phis/ui`), Sites, and
+separately shipped Add-ons. Each lives under its own subpath, because they hold between different parties
+and change 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/addon                what phis and a separately shipped Add-on promise each other
+@phis/contracts/access               the authorization vocabulary phis and @phis/ui both evaluate
+@phis/contracts/signals              the signal vocabulary and address grammar the UI declares in and phis validates
+@phis/contracts/catalog              the Module categories an Add-on declares, the UI groups by and a market filters on
+@phis/contracts/cms                  the CMS node identity both sides derive, and must derive alike
+@phis/contracts/media                the Asset vocabularies both sides store, filter on and judge
+@phis/contracts/http                 the request headers phis and the site UI must spell the same way
+@phis/contracts/locale               the locale this software is authored in
+@phis/contracts/logging              the structured log vocabulary a Site writes and phis reads back
+@phis/contracts/server-capabilities  the capability snapshot phis reports and the UI acts on
+@phis/contracts/site-groups          the membership levels of a Site group, as both ends count them
+@phis/contracts/user-state           the shapes a Module may keep a person's decisions in, and the key grammar
 ```
 
-There is deliberately no root export. A package you can import from the top invites everything that
-two of our packages happen to share; a subpath makes you say which agreement you mean.
+## Before the v1 release, interface versions stay at 1
 
-## `/addon`
+`PHIS_SERVICE_INTERFACE_VERSIONS` and `PHIS_SERVICE_INTERFACE_DIGESTS` in `@phis/contracts/addon` are not
+raised while phis is pre-v1, however much an interface changes. The mechanism they drive is real and
+deliberate -- Core refuses an Add-on whose recorded manifest names a digest this release does not offer --
+and that is exactly why raising a version now is the wrong move: there is no released Add-on to protect, so
+it buys no compatibility, and it takes the installation down. The recorded manifest in
+`config/phis-addons.json` stops matching, the capability snapshot refuses the desired state, and every
+request that resolves a viewer answers 500 until each installed Add-on has been rebundled and upgraded.
 
-The types and constants a phi-server Add-on declares or implements. Types and constants only — no
-runtime code, no `server-only`, no React, no Next.
+An interface that changes before v1 is simply the interface. Both sides are rebuilt from one tree, and the
+version is raised once, when there is something in the field that a wrong assumption would break.
 
-An Add-on is compiled to a single ESM artifact and installed into a running phi-server through the
-`phis` CLI. It is never built into the server. This subpath is the only thing an Add-on compiles
-against; it must not depend on phi-server itself.
+There is deliberately no root export. A package you can import from the top invites everything two of
+our packages happen to share; a subpath makes you say which agreement you mean.
 
 ```sh
-npm install --save-dev @phis/contracts
+npm install @phis/contracts
 ```
 
-For an Add-on author it is a build-time dependency: everything `/addon` exports is erased at compile
-time, apart from a handful of constants.
+## `/addon`
+
+The types and constants an Add-on declares or implements. Types and constants only: no runtime code, no
+`server-only`, no React, no Next.
+
+An Add-on is compiled to a single ESM artifact and installed into a running phis through the `phis` CLI;
+it is never built into the server. This subpath is the only thing an Add-on compiles against, and it must
+not depend on phis itself. For an Add-on author it is a build-time dependency: everything it exports is
+erased at compile time apart from a handful of constants.
+
+What it covers:
+
+- **Manifest** -- `PhisAddonManifestV1`: identity, version, required Core capabilities, the routes an
+  Add-on claims, the services it provides.
+- **Runtime** -- `PhisAddonRuntimeV1`, `PhisAddonHandler`, `PhisAddonRequestContext`. The artifact
+  exports it under the name `phisAddon` (`PhisAddonRuntimeModuleV1`).
+- **Schema** -- `PhisAddonSchemaDescriptor` and its column, index and constraint descriptors. Tables are
+  declared, not migrated by hand; phis applies them.
+- **Service kinds** -- the Core-owned kinds an Add-on may supply an implementation of: Media Storage
+  (`PhisMediaStorageAdapter`, upload plans, object I/O) and Directory. `PHIS_SERVICE_KINDS` names them
+  and `PHIS_SERVICE_INTERFACE_DIGESTS` holds the digest of each kind's current interface; Core refuses an
+  Add-on built against a different digest at install.
+- **Core capabilities** -- `PHIS_CORE_CAPABILITIES`, the capability ids an Add-on may require. Declare
+  against these constants rather than spelling the ids out. The list is the vocabulary and may reserve a
+  name before Core delivers it (`resource-links`, `support`); an Add-on that requires a capability this
+  release does not deliver is refused rather than handed a missing object.
+
+`PHIS_ADDON_ABI_VERSION` is the single number phis checks an Add-on against.
+
+How an Add-on is laid out, compiled, installed, activated and upgraded is described in phis's
+[`ADDON_HOWTO.md`](https://github.com/phis-dev/phis-server/blob/main/ADDON_HOWTO.md); the rules behind it
+are in [`SERVER_ADDONS.md`](https://github.com/phis-dev/phis-server/blob/main/SERVER_ADDONS.md).
 
 ## `/access`
 
-Claim shapes, policy shapes, and the evaluator that decides them. Unlike `/addon`, this one **is**
-runtime code, and it is a real dependency of both packages that use it.
+Claim shapes, policy shapes, and the evaluator that decides them. Unlike `/addon`, this is runtime code
+and a real dependency of both packages that use it.
 
-Two processes decide the same question. phi-server decides it in its guards and API routes; the site
-decides it while rendering — per navigation entry, per tree node, and in the browser, where
-phi-server is not reachable without a round trip. Neither can defer to the other, so both evaluate,
-and one compiled source is the only way both can agree.
+Two processes decide the same question. phis decides it in its guards and API routes; a Site decides it
+while rendering -- per navigation entry, per tree node, and in the browser, where phis is not reachable
+without a round trip. Neither can defer to the other, so both evaluate, and one compiled source is the
+only way both reach the same answer: a stored claim normalised on one side and not on the other admits
+on one and refuses on the other, and neither copy looks wrong on its own.
 
-They did not agree before this subpath existed. A stored claim with `flags: -1` admitted everything
-on the server and nothing in the UI: one side normalised the value, the other did not. Neither copy
-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
+adopts the other's shape.
 
-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.
+
+It is arithmetic both sides must compute alike. A Preset id is derived rather than allocated, so the site
+UI can address a node before any row exists and phis can check that stored wiring points at nodes that
+really exist. A changed constant on one side produces ids that are still well formed and simply name
+nothing. The Page-key convention and the map helper built on top stay with `@phis/ui`.
 
 ## `/signals`
 
-The closed vocabularies a widget's wiring is written in -- scopes, actions, value types -- and the shape
-of a value schema name.
+The closed vocabularies a Widget's wiring is written in -- scopes, actions, value types -- the shape of a
+value schema name, and the address families.
 
-A widget declares what it emits and listens for, the Builder stores that, and phi-server validates it on
-the way in. Two lists, one meaning; and when they were two lists they drifted. `@phis/ui` had grown
-`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".
+A Widget declares what it emits and listens for, the Builder stores that, phis validates it on the way
+in, and the Site delivers it at runtime, so all of them parse the same strings. The rule that says which
+receivers a scope admits, and the controller address the Site scope privileges, live here for the same
+reason.
 
-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.
+Which schemas exist stays with the UI. phis checks that a JSON signal names *a* schema, never which one:
+`isPhiSignalValueSchemaShape` checks the shape, not membership. The UI asks the stricter question because
+it holds the Module registry; phis must not, or it would refuse every third party's schema.
 
-## What `/addon` covers
+## `/catalog`
 
-- **Manifest** — `PhiServerAddonManifestV1`: 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
-  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
-  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.
+What a Module is for, as one closed list: `foundation`, `workspace`, `content`, `media`, `commerce`,
+`identity`, `communication`, `events`, `analytics`, `integration`, `operations`, `other`
+(`PHI_RUNTIME_MODULE_CATEGORIES`).
 
-This list is a promise, not a plan. A capability appears here when Core delivers it, never
-before.
+An Add-on declares it 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 marketplace Add-on -- which
+compiles against this package and nothing else -- filters on it.
 
-`PHI_SERVER_ADDON_ABI_VERSION` is the single number a server checks an Add-on against.
+It is not in `/addon` on purpose: `/addon` is the ABI a third party compiles against, and this list grows
+with the product. phis does not ask the membership question either; a manifest carries categories as
+plain strings, Core checks the shape, and the strict question is asked where a registry is held. The
+labels an operator reads are label-set keys owned by the UI; this subpath holds identifiers only.
 
-## Admission rule
+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. Reading that from `package.json` means nobody has to execute a stranger's
+package to list it. The author writes it; `phis module` checks that the entries are present and well
+formed, and a package that declares nothing is refused at intake.
+
+## `/media`
+
+The words and numbers a Site and phis must 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`.
+
+These values travel and are judged on the other side. The site UI sends a flag mask as a list filter and
+flag values when metadata is saved, and phis filters with `presentation_flags & mask <> 0` and refuses a
+value it does not know. An Asset payload carries `lifecycleStatus` and `deliveryPolicy` as stored, and
+the UI decides from them whether `next/image` may be pointed at the original.
+
+The resolvers come with their vocabulary: `normalizePhiMediaKind` and `resolvePhiMediaKindFromContentType`
+map onto the kind list, so an upload is filed and listed as the same kind on both sides. How a delivery
+URL is built stays with each side, and phis's numeric Space kind never reaches a Site.
+
+## `/http`
 
-Per subpath, and both halves are narrow on purpose.
+The request header names phis reads and the site UI writes: `PHIS_TOKEN_HEADER` (`x-phis-token`),
+`PHIS_SITE_KEY_HEADER`, `PHIS_AREA_HEADER`, `PHIS_REQUEST_PATH_HEADER` and `PHIS_REQUEST_SEARCH_HEADER`.
+A disagreement here is not a type error but a 403 or 400 at runtime.
 
-Into `/addon`: only what **phi-server and a separately shipped Add-on must agree on**. Declarations,
-never implementations.
+## `/locale`
+
+`PHI_CANONICAL_SOURCE_LOCALE`: the locale every label, email template and global message is authored in,
+and therefore the one a translation starts from. It is not a Site's default locale, which is per-Site
+configuration.
+
+## `/logging`
+
+The structured log vocabulary: `PhiLogService` (`phis`, `ui`, `site`, `cli`), `PhiLogLevel`,
+`PhiLoggerContext`, `PhiLogEvent` and the `PhiLogger` interface. A Site and phis both write these records
+to journald, and the log surface in phis parses them back, filtering by exactly these services and
+fields. How a line is serialised is each writer's own concern.
+
+## `/server-capabilities`
+
+The snapshot `/api/v1/site/capabilities` reports: per provider (Core or an Add-on), the capabilities it
+offers and its state (`PhiCapabilitySnapshot`, `PhiCapabilityProvider`, `PhiCapabilityState`). phis
+decides the verdict; the site UI acts on it, deactivating a Module whose provider is not `available` and
+naming the reason in its diagnostics.
+
+## `/site-groups`
+
+The membership ladder of a Site group: `PhiGroupMembershipFlags` (`Member`, `Author`, `Editor`,
+`Manager`, cumulative bits), `PHI_GROUP_MEMBERSHIP_LEVELS` and `readPhiGroupMembershipLevel`. The site UI
+sends `membershipFlags` as an integer and offers the levels to choose from, so both ends must count the
+same bits. The Add-on boundary names levels instead (`PHIS_GROUP_LEVELS` in `/addon`).
+
+## `/user-state`
+
+What a Module may keep per Site about a person who decided something: the closed shape set
+(`PHIS_USER_STATE_SHAPES` -- `flag`, `marker`, `value`, `set`), the `<package>/<key>` grammar, the
+declaration a Module makes (`PhisDeclarableUserStateKey`), and `readPhisUserStateWrite`, which both ends
+call so a refused write is refused the same way in both. phis stores it and is the only party that
+validates; the site UI declares the keys and reads them while rendering. Core's own account facts stay
+bit flags on the membership and account rows and are not this.
+
+## Admission rule
 
-Into `/access`: only what **phi-server and `@phis/ui` must both evaluate**, because each decides it
-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.
+Per subpath, and narrow on purpose. Name the two parties and the sentence they promise each other; if that
+sentence cannot be written down, it does not go in here.
 
-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.
+- `/addon`: only what phis and a separately shipped Add-on must agree on. Declarations, never
+  implementations.
+- `/access`: only what phis and `@phis/ui` must both evaluate, each in its own process. A helper both
+  happen to use is convenience, not a contract.
+- `/catalog`: only vocabularies an Add-on declares a Module in and another party reads back -- closed
+  lists of identifiers, never the words an operator sees.
+- `/media`, `/http`, `/logging`, `/site-groups`, `/server-capabilities`: only what crosses the wire as a
+  value and is judged on the other side. A copy is a contract when disagreeing about it changes what a
+  request returns.
+- `/user-state`: only the shapes and the key grammar both ends check a write against. What a Module keeps
+  under its keys is the Module's business and never named here.
 
-## Documentation
+## License
 
-The full walkthrough — how an Add-on is laid out, compiled, installed, activated, and
-upgraded — lives in phi-server's `ADDON_HOWTO.md`, with the design rationale in
-`SERVER_ADDONS.md`.
+Apache-2.0. See `LICENSE` and `NOTICE`.

package/dist/access.d.ts

@@ -29,7 +29,70 @@ export declare const PhiBaseRole: {
     readonly Developer: number;
     readonly Supporter: number;
     readonly Accountant: number;
+    /**
+     * Works here, and needs nothing else.
+     *
+     * It grants no capability at all, which is what it is for: being Staff decides who may be written to
+     * and who may open a thread with a colleague, and until this bit existed the only way to say it was to
+     * hand out a role that also grants something -- a developer bit to somebody who never touches a log.
+     *
+     * Staff is whoever holds *any* Core role, so every role above implies it and this is the one to give
+     * somebody who holds none of them. Roles an Add-on defines never make anybody Staff: they are
+     * provider-local and say what a person may do inside that Add-on, which is how somebody outside the
+     * company can hold one and remain outside it.
+     */
+    readonly Staff: 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

@@ -29,7 +29,85 @@ export const PhiBaseRole = {
     Developer: 1 << 4,
     Supporter: 1 << 5,
     Accountant: 1 << 6,
+    /**
+     * Works here, and needs nothing else.
+     *
+     * It grants no capability at all, which is what it is for: being Staff decides who may be written to
+     * and who may open a thread with a colleague, and until this bit existed the only way to say it was to
+     * hand out a role that also grants something -- a developer bit to somebody who never touches a log.
+     *
+     * Staff is whoever holds *any* Core role, so every role above implies it and this is the one to give
+     * somebody who holds none of them. Roles an Add-on defines never make anybody Staff: they are
+     * provider-local and say what a person may do inside that Add-on, which is how somebody outside the
+     * company can hold one and remain outside it.
+     */
+    Staff: 1 << 7,
 };
+/**
+ * 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,6 +1,11 @@
 export * from "./addon.js";
+export * from "./assets.js";
 export * from "./capabilities.js";
 export * from "./core.js";
 export * from "./media-storage.js";
 export * from "./queries.js";
+export * from "./resource-links.js";
 export * from "./schema.js";
+export * from "./support.js";
+export * from "./threads.js";
+export * from "./translation.js";

package/dist/addon-index.js

@@ -1,6 +1,11 @@
 export * from "./addon.js";
+export * from "./assets.js";
 export * from "./capabilities.js";
 export * from "./core.js";
 export * from "./media-storage.js";
 export * from "./queries.js";
+export * from "./resource-links.js";
 export * from "./schema.js";
+export * from "./support.js";
+export * from "./threads.js";
+export * from "./translation.js";