@phis/contracts 0.2.0 → 0.4.0

package/dist/cms.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The numbers a CMS row carries, in the one reading both sides must give them.
+ *
+ * A status, a Region type, a visibility mask and a flag set are written by the site UI, checked and
+ * stored by phi-server, and read back by both -- as columns, as fields of a write payload, and as
+ * values inside a stored tree. They are the same kind of agreement as the identity below and were
+ * kept the same way the arithmetic was: two files, identical line for line, in two repositories.
+ *
+ * The visibility mask is the one that shows what that costs. Its bits are not dense -- public 1,
+ * app 2, admin 8, editor 16, accounting 64, builder 256 -- so a side that renumbered them would not
+ * fail anything loudly. It would store a Page in a different Area than the other side reads it from,
+ * and every row would look correct where it was written.
+ */
+export declare const PhiCmsPageType: {
+    readonly Standard: 0;
+    readonly Landing: 1;
+    readonly Legal: 2;
+    readonly System: 3;
+    readonly Redirect: 4;
+};
+export declare const PhiCmsStatus: {
+    readonly Draft: 0;
+    readonly Published: 1;
+    readonly Archived: 2;
+    readonly Deleted: 3;
+};
+export declare const PhiCmsRegionStatus: {
+    readonly Draft: 0;
+    readonly Active: 1;
+    readonly Disabled: 2;
+};
+/** Numbered with room between the groups, so a Region can be added beside its neighbours. */
+export declare const PhiCmsRegionType: {
+    readonly HeaderTop: 10;
+    readonly HeaderMain: 11;
+    readonly HeaderBottom: 12;
+    readonly SiderLeft: 20;
+    readonly SiderRight: 21;
+    readonly Hero: 25;
+    readonly Content: 30;
+    readonly FooterTop: 39;
+    readonly Footer: 40;
+    readonly FooterBottom: 41;
+    readonly Drawer: 50;
+};
+export type PhiCmsRegionTypeValue = (typeof PhiCmsRegionType)[keyof typeof PhiCmsRegionType];
+/**
+ * Which Areas a row is visible in, as one value per Area rather than a running number.
+ *
+ * Bits 2, 5 and 7 are unassigned. That is what makes the numbers worth stating once: 8 reads like the
+ * fourth Area and is the third, and phi-server stores it as `area_id` where nothing spells it out.
+ */
+export declare const PhiCmsVisibilityContext: {
+    readonly PublicArea: number;
+    readonly AppArea: number;
+    readonly AdminArea: number;
+    readonly EditorArea: number;
+    readonly AccountingArea: number;
+    readonly BuilderArea: number;
+};
+/**
+ * The flags a CMS row carries, in the one numbering both sides read them from.
+ *
+ * Not every flag reaches every kind of row -- `Collapsed` is a Region's answer and `MobileOnly` a
+ * renderable's -- but they share one space, because a row is stored as a row whatever it holds.
+ *
+ * `NoIndex` is a Page's, and it is the Site's answer rather than the preset's: a Module states what a
+ * Page it ships starts out as, and the Builder's switch is what decides from then on. That is why it
+ * lives here, on the record, and not on the route descriptor -- a descriptor is read fresh on every
+ * request and would overrule the Operator on every one of them.
+ */
+export declare const PhiCmsFlags: {
+    readonly SiteCustom: number;
+    readonly Hidden: number;
+    readonly MobileOnly: number;
+    readonly DesktopOnly: number;
+    readonly Collapsed: number;
+    readonly NoTranslate: number;
+    readonly NoIndex: number;
+};
+export declare const PhiCmsRevisionFlags: {
+    readonly Draft: number;
+    readonly Published: number;
+    readonly Deleted: number;
+};
+export declare const DEFAULT_PHI_CMS_VISIBILITY_MASK: number;
+declare const PHI_CMS_INSTANCE_ID_BRAND: unique symbol;
+export type PhiCmsInstanceId = string & {
+    readonly [PHI_CMS_INSTANCE_ID_BRAND]: "PhiCmsInstanceId";
+};
+export type PhiCmsInstanceOrigin = "preset" | "draft";
+export type PhiCmsInstanceDomain = "area" | "page" | "navigation";
+export type PhiCmsInstanceIdDescriptor = {
+    version: 1;
+    origin: "preset";
+    domain: PhiCmsInstanceDomain;
+} | {
+    version: 1;
+    origin: "draft";
+    domain: PhiCmsInstanceDomain;
+    draftRevisionId: number;
+    sequence: number;
+};
+export type PhiCmsPresetInstanceIdentity = {
+    domain: PhiCmsInstanceDomain;
+    ownerModuleId: string;
+    presetKey: string;
+    nodeKey: string;
+};
+export declare function createPhiDraftCmsInstanceId({ domain, draftRevisionId, sequence, }: {
+    domain: PhiCmsInstanceDomain;
+    draftRevisionId: number;
+    sequence: number;
+}): PhiCmsInstanceId;
+export declare function createPhiPresetCmsInstanceId({ domain, ownerModuleId, presetKey, nodeKey, }: PhiCmsPresetInstanceIdentity): PhiCmsInstanceId;
+export declare function readPhiCmsInstanceIdDescriptor(value: unknown): PhiCmsInstanceIdDescriptor | null;
+export declare function isPhiCmsInstanceId(value: unknown): value is PhiCmsInstanceId;
+export declare function readPhiCmsInstanceId(value: unknown): PhiCmsInstanceId | null;
+export declare function comparePhiCmsInstanceIds(left: PhiCmsInstanceId, right: PhiCmsInstanceId): 1 | 0 | -1;
+export {};

package/dist/cms.js

@@ -0,0 +1,270 @@
+/**
+ * The numbers a CMS row carries, in the one reading both sides must give them.
+ *
+ * A status, a Region type, a visibility mask and a flag set are written by the site UI, checked and
+ * stored by phi-server, and read back by both -- as columns, as fields of a write payload, and as
+ * values inside a stored tree. They are the same kind of agreement as the identity below and were
+ * kept the same way the arithmetic was: two files, identical line for line, in two repositories.
+ *
+ * The visibility mask is the one that shows what that costs. Its bits are not dense -- public 1,
+ * app 2, admin 8, editor 16, accounting 64, builder 256 -- so a side that renumbered them would not
+ * fail anything loudly. It would store a Page in a different Area than the other side reads it from,
+ * and every row would look correct where it was written.
+ */
+export const PhiCmsPageType = {
+    Standard: 0,
+    Landing: 1,
+    Legal: 2,
+    System: 3,
+    Redirect: 4,
+};
+export const PhiCmsStatus = {
+    Draft: 0,
+    Published: 1,
+    Archived: 2,
+    Deleted: 3,
+};
+export const PhiCmsRegionStatus = {
+    Draft: 0,
+    Active: 1,
+    Disabled: 2,
+};
+/** Numbered with room between the groups, so a Region can be added beside its neighbours. */
+export const PhiCmsRegionType = {
+    HeaderTop: 10,
+    HeaderMain: 11,
+    HeaderBottom: 12,
+    SiderLeft: 20,
+    SiderRight: 21,
+    Hero: 25,
+    Content: 30,
+    FooterTop: 39,
+    Footer: 40,
+    FooterBottom: 41,
+    Drawer: 50,
+};
+/**
+ * Which Areas a row is visible in, as one value per Area rather than a running number.
+ *
+ * Bits 2, 5 and 7 are unassigned. That is what makes the numbers worth stating once: 8 reads like the
+ * fourth Area and is the third, and phi-server stores it as `area_id` where nothing spells it out.
+ */
+export const PhiCmsVisibilityContext = {
+    PublicArea: 1 << 0,
+    AppArea: 1 << 1,
+    AdminArea: 1 << 3,
+    EditorArea: 1 << 4,
+    AccountingArea: 1 << 6,
+    BuilderArea: 1 << 8,
+};
+/**
+ * The flags a CMS row carries, in the one numbering both sides read them from.
+ *
+ * Not every flag reaches every kind of row -- `Collapsed` is a Region's answer and `MobileOnly` a
+ * renderable's -- but they share one space, because a row is stored as a row whatever it holds.
+ *
+ * `NoIndex` is a Page's, and it is the Site's answer rather than the preset's: a Module states what a
+ * Page it ships starts out as, and the Builder's switch is what decides from then on. That is why it
+ * lives here, on the record, and not on the route descriptor -- a descriptor is read fresh on every
+ * request and would overrule the Operator on every one of them.
+ */
+export const PhiCmsFlags = {
+    SiteCustom: 1 << 0,
+    Hidden: 1 << 1,
+    MobileOnly: 1 << 2,
+    DesktopOnly: 1 << 3,
+    Collapsed: 1 << 4,
+    NoTranslate: 1 << 5,
+    NoIndex: 1 << 6,
+};
+export const PhiCmsRevisionFlags = {
+    Draft: 1 << 0,
+    Published: 1 << 1,
+    Deleted: 1 << 2,
+};
+export const DEFAULT_PHI_CMS_VISIBILITY_MASK = PhiCmsVisibilityContext.PublicArea;
+/**
+ * The identity a CMS node carries, in the one encoding both sides must compute alike.
+ *
+ * A node id is not allocated, it is derived: a Preset node's id is a hash of the Module, the preset
+ * and the node key, so the same node has the same id before any row exists and after every
+ * republish. The site UI derives it to address blocks and Pages; phi-server derives it to check that
+ * stored wiring points at nodes that are really there, and to write Page identities of its own.
+ *
+ * Which is why this cannot be two implementations agreeing by inspection -- and it was exactly that:
+ * `hashPresetIdentity` stood twice, line for line, in `@phis/ui` and in phi-server. The two had to
+ * produce identical bytes forever, and a changed constant on one side would not have failed
+ * anything loudly. It would have given one process a different Page identity than the other, and
+ * Pages would have stopped resolving with nothing to point at.
+ *
+ * That makes it the exception this package's rule allows for. Everywhere else the rule is shape here,
+ * membership with whoever holds the registry; here there is no shape to check, only an arithmetic --
+ * and the reason it belongs here is precisely that the arithmetic must be one.
+ */
+const PHI_CMS_INSTANCE_ID_BYTE_LENGTH = 12;
+const PHI_CMS_INSTANCE_ID_ENCODED_LENGTH = 16;
+const PHI_CMS_INSTANCE_ID_VERSION = 1;
+const PHI_CMS_INSTANCE_ID_ORIGIN_PRESET = 1;
+const PHI_CMS_INSTANCE_ID_ORIGIN_DRAFT = 2;
+const PHI_CMS_INSTANCE_ID_VERSION_SHIFT = 4;
+const PHI_CMS_INSTANCE_ID_ORIGIN_MASK = 0x0f;
+const PHI_CMS_INSTANCE_ID_PATTERN = /^[A-Za-z0-9_-]{16}$/;
+const PHI_CMS_BASE64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+const PHI_CMS_MAX_DRAFT_REVISION_ID = 0xffff_ffff_ffff;
+const PHI_CMS_MAX_DRAFT_SEQUENCE = 0xffff_ffff;
+const PHI_CMS_INSTANCE_DOMAIN_CODES = {
+    area: 1,
+    page: 2,
+    navigation: 3,
+};
+const PHI_CMS_INSTANCE_DOMAINS_BY_CODE = new Map(Object.entries(PHI_CMS_INSTANCE_DOMAIN_CODES).map(([domain, code]) => [
+    code,
+    domain,
+]));
+function encodeBase64Url(bytes) {
+    let output = "";
+    for (let index = 0; index < bytes.length; index += 3) {
+        const first = bytes[index] ?? 0;
+        const second = bytes[index + 1] ?? 0;
+        const third = bytes[index + 2] ?? 0;
+        output += PHI_CMS_BASE64URL_ALPHABET[first >>> 2];
+        output += PHI_CMS_BASE64URL_ALPHABET[((first & 0x03) << 4) | (second >>> 4)];
+        output += PHI_CMS_BASE64URL_ALPHABET[((second & 0x0f) << 2) | (third >>> 6)];
+        output += PHI_CMS_BASE64URL_ALPHABET[third & 0x3f];
+    }
+    return output;
+}
+function decodeBase64Url(value) {
+    if (!PHI_CMS_INSTANCE_ID_PATTERN.test(value)) {
+        return null;
+    }
+    const bytes = new Uint8Array(PHI_CMS_INSTANCE_ID_BYTE_LENGTH);
+    for (let index = 0; index < value.length; index += 4) {
+        const first = PHI_CMS_BASE64URL_ALPHABET.indexOf(value[index]);
+        const second = PHI_CMS_BASE64URL_ALPHABET.indexOf(value[index + 1]);
+        const third = PHI_CMS_BASE64URL_ALPHABET.indexOf(value[index + 2]);
+        const fourth = PHI_CMS_BASE64URL_ALPHABET.indexOf(value[index + 3]);
+        if (first < 0 || second < 0 || third < 0 || fourth < 0) {
+            return null;
+        }
+        const byteIndex = (index / 4) * 3;
+        bytes[byteIndex] = (first << 2) | (second >>> 4);
+        bytes[byteIndex + 1] = ((second & 0x0f) << 4) | (third >>> 2);
+        bytes[byteIndex + 2] = ((third & 0x03) << 6) | fourth;
+    }
+    return bytes;
+}
+function createHeader(origin) {
+    return (PHI_CMS_INSTANCE_ID_VERSION << PHI_CMS_INSTANCE_ID_VERSION_SHIFT) | origin;
+}
+function readHeader(bytes) {
+    const version = bytes[0] >>> PHI_CMS_INSTANCE_ID_VERSION_SHIFT;
+    const origin = bytes[0] & PHI_CMS_INSTANCE_ID_ORIGIN_MASK;
+    return { version, origin };
+}
+function assertSafeIntegerInRange(value, min, max, label) {
+    if (!Number.isSafeInteger(value) || value < min || value > max) {
+        throw new Error(`${label} must be a safe integer from ${min} through ${max}.`);
+    }
+}
+function writeUnsignedBigEndian(bytes, offset, length, value) {
+    let remaining = value;
+    for (let index = offset + length - 1; index >= offset; index -= 1) {
+        bytes[index] = remaining % 256;
+        remaining = Math.floor(remaining / 256);
+    }
+}
+function readUnsignedBigEndian(bytes, offset, length) {
+    let value = 0;
+    for (let index = offset; index < offset + length; index += 1) {
+        value = (value * 256) + bytes[index];
+    }
+    return value;
+}
+function normalizeIdentityPart(value, label) {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new Error(`${label} must not be empty.`);
+    }
+    return normalized;
+}
+function hashPresetIdentity(value) {
+    const bytes = new TextEncoder().encode(value);
+    const state = new Uint32Array([0x811c9dc5, 0x9e3779b9, 0x85ebca6b]);
+    const primes = [0x01000193, 0x27d4eb2d, 0x165667b1];
+    for (const byte of bytes) {
+        for (let index = 0; index < state.length; index += 1) {
+            state[index] = Math.imul(state[index] ^ (byte + index * 17), primes[index]) >>> 0;
+            state[index] = state[index] ^ (state[index] >>> 13);
+        }
+    }
+    const result = new Uint8Array(10);
+    for (let index = 0; index < result.length; index += 1) {
+        const lane = index % state.length;
+        state[lane] = Math.imul(state[lane] ^ (index + bytes.length), primes[lane]) >>> 0;
+        result[index] = state[lane] >>> ((index % 4) * 8);
+    }
+    return result;
+}
+export function createPhiDraftCmsInstanceId({ domain, draftRevisionId, sequence, }) {
+    assertSafeIntegerInRange(draftRevisionId, 1, PHI_CMS_MAX_DRAFT_REVISION_ID, "Draft revision id");
+    assertSafeIntegerInRange(sequence, 1, PHI_CMS_MAX_DRAFT_SEQUENCE, "Draft node sequence");
+    const bytes = new Uint8Array(PHI_CMS_INSTANCE_ID_BYTE_LENGTH);
+    bytes[0] = createHeader(PHI_CMS_INSTANCE_ID_ORIGIN_DRAFT);
+    bytes[1] = PHI_CMS_INSTANCE_DOMAIN_CODES[domain];
+    writeUnsignedBigEndian(bytes, 2, 6, draftRevisionId);
+    writeUnsignedBigEndian(bytes, 8, 4, sequence);
+    return encodeBase64Url(bytes);
+}
+export function createPhiPresetCmsInstanceId({ domain, ownerModuleId, presetKey, nodeKey, }) {
+    const identity = [
+        `v${PHI_CMS_INSTANCE_ID_VERSION}`,
+        domain,
+        normalizeIdentityPart(ownerModuleId, "Preset owner module id"),
+        normalizeIdentityPart(presetKey, "Preset key"),
+        normalizeIdentityPart(nodeKey, "Preset node key"),
+    ].join("\u001f");
+    const bytes = new Uint8Array(PHI_CMS_INSTANCE_ID_BYTE_LENGTH);
+    bytes[0] = createHeader(PHI_CMS_INSTANCE_ID_ORIGIN_PRESET);
+    bytes[1] = PHI_CMS_INSTANCE_DOMAIN_CODES[domain];
+    bytes.set(hashPresetIdentity(identity), 2);
+    return encodeBase64Url(bytes);
+}
+export function readPhiCmsInstanceIdDescriptor(value) {
+    if (typeof value !== "string" || value.length !== PHI_CMS_INSTANCE_ID_ENCODED_LENGTH) {
+        return null;
+    }
+    const bytes = decodeBase64Url(value);
+    if (!bytes) {
+        return null;
+    }
+    const header = readHeader(bytes);
+    if (header.version !== PHI_CMS_INSTANCE_ID_VERSION) {
+        return null;
+    }
+    const domain = PHI_CMS_INSTANCE_DOMAINS_BY_CODE.get(bytes[1]);
+    if (!domain) {
+        return null;
+    }
+    if (header.origin === PHI_CMS_INSTANCE_ID_ORIGIN_PRESET) {
+        return { version: 1, origin: "preset", domain };
+    }
+    if (header.origin !== PHI_CMS_INSTANCE_ID_ORIGIN_DRAFT) {
+        return null;
+    }
+    const draftRevisionId = readUnsignedBigEndian(bytes, 2, 6);
+    const sequence = readUnsignedBigEndian(bytes, 8, 4);
+    if (draftRevisionId < 1 || sequence < 1) {
+        return null;
+    }
+    return { version: 1, origin: "draft", domain, draftRevisionId, sequence };
+}
+export function isPhiCmsInstanceId(value) {
+    return readPhiCmsInstanceIdDescriptor(value) !== null;
+}
+export function readPhiCmsInstanceId(value) {
+    return isPhiCmsInstanceId(value) ? value : null;
+}
+export function comparePhiCmsInstanceIds(left, right) {
+    return left === right ? 0 : left < right ? -1 : 1;
+}

package/dist/core.d.ts

@@ -14,7 +14,7 @@
  * without hashing anything -- Core recomputes them and checks, which is where that belongs.
  */
 /** The Core capabilities an Add-on may require. */
-export declare const PHI_SERVER_CORE_CAPABILITIES: {
+export declare const PHIS_CORE_CAPABILITIES: {
     readonly authentication: "@phis/server/authentication:v1";
     /**
      * "May this actor", in all three of its sources: does the row belong to them, what level do they
@@ -31,6 +31,14 @@ export declare const PHI_SERVER_CORE_CAPABILITIES: {
     /** Group facts -- which groups exist, who is in them. What follows from them is `authorization`. */
     readonly groups: "@phis/server/groups:v1";
     readonly storage: "@phis/server/storage:v1";
+    /**
+     * The files a row carries, in the slots its table declared.
+     *
+     * Separate from `storage` because they answer different questions. `storage` hands out a key space an
+     * Add-on manages itself; this hands out places Core knows about, which is what makes the file of a
+     * deleted row collectable rather than merely gone from view.
+     */
+    readonly assets: "@phis/server/assets:v1";
     /** Reading the secrets an operator set for this Add-on, and no others. */
     readonly secrets: "@phis/server/secrets:v1";
     /** Reading what an operator configured for this Add-on on this Site. */
@@ -38,7 +46,29 @@ export declare const PHI_SERVER_CORE_CAPABILITIES: {
     /** Whether the acting user holds one of this Add-on's own declared roles. */
     readonly roles: "@phis/server/roles:v1";
 };
-export type PhiServerCoreCapabilityId = (typeof PHI_SERVER_CORE_CAPABILITIES)[keyof typeof PHI_SERVER_CORE_CAPABILITIES];
+export type PhisCoreCapabilityId = (typeof PHIS_CORE_CAPABILITIES)[keyof typeof PHIS_CORE_CAPABILITIES];
+/**
+ * What Core tells an Add-on about after the fact.
+ *
+ * An integration that mirrors a conversation cannot wait to be asked: somebody writes a reply here and
+ * it has to appear over there, and no request the Add-on serves is involved. Polling would be the
+ * alternative, and polling for "did anybody write anything" is the Site-wide read every capability here
+ * is shaped to prevent.
+ *
+ * An event is delivered only to an Add-on linked to the thread it happened in, and a message this same
+ * Add-on imported is never announced back to it -- which is what stops a mirror from echoing.
+ *
+ * The list is short on purpose and grows when an Add-on needs an entry, the way the capability catalogue
+ * does. Every event a Site could emit, declared in advance, would be a contract to get wrong.
+ */
+export declare const PHIS_ADDON_EVENTS: {
+    readonly threadMessageCreated: "thread.message.created";
+    readonly threadMessageUpdated: "thread.message.updated";
+    readonly threadStatusChanged: "thread.status.changed";
+    /** The link itself is gone; what follows from that is the Add-on's own business. */
+    readonly threadLinkRemoved: "thread.link.removed";
+};
+export type PhisAddonEventId = (typeof PHIS_ADDON_EVENTS)[keyof typeof PHIS_ADDON_EVENTS];
 /**
  * The Core-owned service kinds an Add-on may implement.
  *
@@ -46,11 +76,20 @@ export type PhiServerCoreCapabilityId = (typeof PHI_SERVER_CORE_CAPABILITIES)[ke
  * is something Core already owns and an Add-on supplies an implementation of -- S3 for Media Storage,
  * LDAP for a Directory. Core keeps selecting the configured implementation itself.
  */
-export declare const PHI_SERVER_SERVICE_KINDS: {
+export declare const PHIS_SERVICE_KINDS: {
     readonly mediaStorage: "@phis/server/service/media-storage";
     readonly directory: "@phis/server/service/directory";
+    /**
+     * Turning text in one language into text in another.
+     *
+     * A kind rather than a capability for the same reason as the two above: Core owns the question and
+     * keeps asking it, and what an implementation talks to -- a vendor, a model on the machine, a
+     * catalogue it maintains itself -- is its own business. Several may be installed at once; the
+     * operator selects which one an installation uses.
+     */
+    readonly translation: "@phis/server/service/translation";
 };
-export type PhiServerServiceKind = (typeof PHI_SERVER_SERVICE_KINDS)[keyof typeof PHI_SERVER_SERVICE_KINDS];
+export type PhisServiceKind = (typeof PHIS_SERVICE_KINDS)[keyof typeof PHIS_SERVICE_KINDS];
 /**
  * The digest of the interface each service kind currently has.
  *
@@ -61,6 +100,13 @@ export type PhiServerServiceKind = (typeof PHI_SERVER_SERVICE_KINDS)[keyof typeo
  *
  * The digest is `sha256("phi-server-service-kind:<kind>:v<interface version>")`. That recipe is
  * documented for whoever has to produce the next value; nothing needs to run it to read a manifest.
+ *
+ * **Before the v1 release every version here stays at 1, whatever changes shape.** There is no released
+ * Add-on to protect and nothing in the field built against an older interface, so raising a version buys
+ * no compatibility and costs the installation: the recorded manifest of every installed Add-on stops
+ * matching, `buildPhisCapabilitySnapshot` refuses the desired state, and every request that resolves a
+ * viewer answers 500 until each Add-on has been rebundled and upgraded. An interface that changes before
+ * v1 is simply the interface, and both sides are rebuilt from one tree.
  */
-export declare const PHI_SERVER_SERVICE_INTERFACE_VERSIONS: Readonly<Record<PhiServerServiceKind, number>>;
-export declare const PHI_SERVER_SERVICE_INTERFACE_DIGESTS: Readonly<Record<PhiServerServiceKind, string>>;
+export declare const PHIS_SERVICE_INTERFACE_VERSIONS: Readonly<Record<PhisServiceKind, number>>;
+export declare const PHIS_SERVICE_INTERFACE_DIGESTS: Readonly<Record<PhisServiceKind, string>>;

package/dist/core.js

@@ -14,7 +14,7 @@
  * without hashing anything -- Core recomputes them and checks, which is where that belongs.
  */
 /** The Core capabilities an Add-on may require. */
-export const PHI_SERVER_CORE_CAPABILITIES = {
+export const PHIS_CORE_CAPABILITIES = {
     authentication: "@phis/server/authentication:v1",
     /**
      * "May this actor", in all three of its sources: does the row belong to them, what level do they
@@ -31,6 +31,14 @@ export const PHI_SERVER_CORE_CAPABILITIES = {
     /** Group facts -- which groups exist, who is in them. What follows from them is `authorization`. */
     groups: "@phis/server/groups:v1",
     storage: "@phis/server/storage:v1",
+    /**
+     * The files a row carries, in the slots its table declared.
+     *
+     * Separate from `storage` because they answer different questions. `storage` hands out a key space an
+     * Add-on manages itself; this hands out places Core knows about, which is what makes the file of a
+     * deleted row collectable rather than merely gone from view.
+     */
+    assets: "@phis/server/assets:v1",
     /** Reading the secrets an operator set for this Add-on, and no others. */
     secrets: "@phis/server/secrets:v1",
     /** Reading what an operator configured for this Add-on on this Site. */
@@ -38,6 +46,27 @@ export const PHI_SERVER_CORE_CAPABILITIES = {
     /** Whether the acting user holds one of this Add-on's own declared roles. */
     roles: "@phis/server/roles:v1",
 };
+/**
+ * What Core tells an Add-on about after the fact.
+ *
+ * An integration that mirrors a conversation cannot wait to be asked: somebody writes a reply here and
+ * it has to appear over there, and no request the Add-on serves is involved. Polling would be the
+ * alternative, and polling for "did anybody write anything" is the Site-wide read every capability here
+ * is shaped to prevent.
+ *
+ * An event is delivered only to an Add-on linked to the thread it happened in, and a message this same
+ * Add-on imported is never announced back to it -- which is what stops a mirror from echoing.
+ *
+ * The list is short on purpose and grows when an Add-on needs an entry, the way the capability catalogue
+ * does. Every event a Site could emit, declared in advance, would be a contract to get wrong.
+ */
+export const PHIS_ADDON_EVENTS = {
+    threadMessageCreated: "thread.message.created",
+    threadMessageUpdated: "thread.message.updated",
+    threadStatusChanged: "thread.status.changed",
+    /** The link itself is gone; what follows from that is the Add-on's own business. */
+    threadLinkRemoved: "thread.link.removed",
+};
 /**
  * The Core-owned service kinds an Add-on may implement.
  *
@@ -45,9 +74,18 @@ export const PHI_SERVER_CORE_CAPABILITIES = {
  * is something Core already owns and an Add-on supplies an implementation of -- S3 for Media Storage,
  * LDAP for a Directory. Core keeps selecting the configured implementation itself.
  */
-export const PHI_SERVER_SERVICE_KINDS = {
+export const PHIS_SERVICE_KINDS = {
     mediaStorage: "@phis/server/service/media-storage",
     directory: "@phis/server/service/directory",
+    /**
+     * Turning text in one language into text in another.
+     *
+     * A kind rather than a capability for the same reason as the two above: Core owns the question and
+     * keeps asking it, and what an implementation talks to -- a vendor, a model on the machine, a
+     * catalogue it maintains itself -- is its own business. Several may be installed at once; the
+     * operator selects which one an installation uses.
+     */
+    translation: "@phis/server/service/translation",
 };
 /**
  * The digest of the interface each service kind currently has.
@@ -59,12 +97,21 @@ export const PHI_SERVER_SERVICE_KINDS = {
  *
  * The digest is `sha256("phi-server-service-kind:<kind>:v<interface version>")`. That recipe is
  * documented for whoever has to produce the next value; nothing needs to run it to read a manifest.
+ *
+ * **Before the v1 release every version here stays at 1, whatever changes shape.** There is no released
+ * Add-on to protect and nothing in the field built against an older interface, so raising a version buys
+ * no compatibility and costs the installation: the recorded manifest of every installed Add-on stops
+ * matching, `buildPhisCapabilitySnapshot` refuses the desired state, and every request that resolves a
+ * viewer answers 500 until each Add-on has been rebundled and upgraded. An interface that changes before
+ * v1 is simply the interface, and both sides are rebuilt from one tree.
  */
-export const PHI_SERVER_SERVICE_INTERFACE_VERSIONS = {
-    [PHI_SERVER_SERVICE_KINDS.mediaStorage]: 1,
-    [PHI_SERVER_SERVICE_KINDS.directory]: 1,
+export const PHIS_SERVICE_INTERFACE_VERSIONS = {
+    [PHIS_SERVICE_KINDS.mediaStorage]: 1,
+    [PHIS_SERVICE_KINDS.directory]: 1,
+    [PHIS_SERVICE_KINDS.translation]: 1,
 };
-export const PHI_SERVER_SERVICE_INTERFACE_DIGESTS = {
-    [PHI_SERVER_SERVICE_KINDS.mediaStorage]: "45a871522511f7d77841ca8dd0113b423b3cfd4cb921f143cd1d3d116cab6952",
-    [PHI_SERVER_SERVICE_KINDS.directory]: "2cac7397c7beb1b8e71fc67f5cae3be89182dddf096895570a15deafa1adbfc9",
+export const PHIS_SERVICE_INTERFACE_DIGESTS = {
+    [PHIS_SERVICE_KINDS.mediaStorage]: "45a871522511f7d77841ca8dd0113b423b3cfd4cb921f143cd1d3d116cab6952",
+    [PHIS_SERVICE_KINDS.directory]: "2cac7397c7beb1b8e71fc67f5cae3be89182dddf096895570a15deafa1adbfc9",
+    [PHIS_SERVICE_KINDS.translation]: "9bae2e7b92ded5cdde9321939a3bb8cd589f6e1ef8bca7bc5f65608313b3207d",
 };

package/dist/http.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The request headers phis and the site UI must spell the same way.
+ *
+ * These five names are a wire protocol between processes that deploy independently. phis reads them in
+ * its guards and route handlers; the site UI writes them in its proxies, gateways and browser widgets.
+ * A disagreement is not a type error and not a failing test -- it is a 403 from `guardApiV1` or a 400
+ * from `requireSiteFromExplicitKeyRequest`, at runtime, in whichever direction the mismatch happens to
+ * point.
+ *
+ * They were string literals in both repositories before this file existed, eighty-odd of them, and the
+ * one place that had bothered to name a constant named it in only one of the two. Renaming the prefix
+ * from `x-phi-` to `x-phis-` is what made that visible; the point of collecting them here is that the
+ * next such change is one edit rather than a search.
+ */
+/** Carries the public or internal API token on every `/api/v1/*` request. */
+export declare const PHIS_TOKEN_HEADER: "x-phis-token";
+/**
+ * Names the Site a request is scoped to, and is the only thing that does.
+ *
+ * There is deliberately no host, origin or referer fallback: those are caller-controlled, so a request
+ * without this header could otherwise claim any Site whose hostname it spoofed.
+ */
+export declare const PHIS_SITE_KEY_HEADER: "x-phis-site-key";
+/** Names the CMS area a media request acts in, which decides what the actor may reach. */
+export declare const PHIS_AREA_HEADER: "x-phis-area";
+/**
+ * Hand the original request path and query from the site proxy to the server helpers behind it.
+ *
+ * Both are set and read inside the site runtime and never reach phis; they exist because a Server
+ * Component cannot otherwise see the URL the proxy rewrote.
+ */
+export declare const PHIS_REQUEST_PATH_HEADER: "x-phis-request-path";
+export declare const PHIS_REQUEST_SEARCH_HEADER: "x-phis-request-search";

package/dist/http.js

@@ -0,0 +1,33 @@
+/**
+ * The request headers phis and the site UI must spell the same way.
+ *
+ * These five names are a wire protocol between processes that deploy independently. phis reads them in
+ * its guards and route handlers; the site UI writes them in its proxies, gateways and browser widgets.
+ * A disagreement is not a type error and not a failing test -- it is a 403 from `guardApiV1` or a 400
+ * from `requireSiteFromExplicitKeyRequest`, at runtime, in whichever direction the mismatch happens to
+ * point.
+ *
+ * They were string literals in both repositories before this file existed, eighty-odd of them, and the
+ * one place that had bothered to name a constant named it in only one of the two. Renaming the prefix
+ * from `x-phi-` to `x-phis-` is what made that visible; the point of collecting them here is that the
+ * next such change is one edit rather than a search.
+ */
+/** Carries the public or internal API token on every `/api/v1/*` request. */
+export const PHIS_TOKEN_HEADER = "x-phis-token";
+/**
+ * Names the Site a request is scoped to, and is the only thing that does.
+ *
+ * There is deliberately no host, origin or referer fallback: those are caller-controlled, so a request
+ * without this header could otherwise claim any Site whose hostname it spoofed.
+ */
+export const PHIS_SITE_KEY_HEADER = "x-phis-site-key";
+/** Names the CMS area a media request acts in, which decides what the actor may reach. */
+export const PHIS_AREA_HEADER = "x-phis-area";
+/**
+ * Hand the original request path and query from the site proxy to the server helpers behind it.
+ *
+ * Both are set and read inside the site runtime and never reach phis; they exist because a Server
+ * Component cannot otherwise see the URL the proxy rewrote.
+ */
+export const PHIS_REQUEST_PATH_HEADER = "x-phis-request-path";
+export const PHIS_REQUEST_SEARCH_HEADER = "x-phis-request-search";

package/dist/locale.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The language this software is written in.
+ *
+ * Not a default and not a preference: it is the locale every label, every email template and every
+ * global message is authored in, and therefore the one a translation starts from. `TRANSLATIONS.md`
+ * fixes it -- global messages in `phis.tr_msg` always use English as their canonical source, while a
+ * Site's own messages use the immutable `sourceLocale` chosen when the Site was created.
+ *
+ * It was called DEFAULT_LOCALE on both sides, which is the name of a different thing: a Site's default
+ * locale is configuration, stored per Site in `sites.default_locale`, and an installation may set it to
+ * anything. Under one name the two were indistinguishable at the call site, and a reader could not tell
+ * whether a line stated a fact about the source text or made an assumption about somebody's Site.
+ */
+export declare const PHI_CANONICAL_SOURCE_LOCALE = "en";