@phis/contracts 0.2.0 → 0.3.1

package/dist/catalog.js

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

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,7 @@ 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];
 /**
  * The Core-owned service kinds an Add-on may implement.
  *
@@ -46,11 +54,11 @@ 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";
 };
-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.
  *
@@ -62,5 +70,5 @@ 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.
  */
-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. */
@@ -45,7 +53,7 @@ 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",
 };
@@ -60,11 +68,11 @@ 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.
  */
-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,
 };
-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",
 };

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";