@phis/contracts 0.2.0 → 0.3.1

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

package/dist/locale.js

@@ -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 const PHI_CANONICAL_SOURCE_LOCALE = "en";

package/dist/logging.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The log vocabulary phis and the site UI must both know.
+ *
+ * Two processes write these records and one of them reads all of them: a Site runtime and this server
+ * both emit structured lines to journald, and the admin log surface in phis parses them back --
+ * filtering by service, splitting by level, and projecting exactly the fields named below. The writer
+ * and the reader are therefore two ends of one format, and neither can defer to the other.
+ *
+ * They did not agree before this file existed. `service` was a closed list in both places, and the two
+ * lists drifted: phis admitted "phi-ui" while the UI wrote "phi-shared". Nothing failed. The records
+ * simply carried a name the reader never offered as a filter, so the events were there and not
+ * findable -- the same failure mode, and the same cure, as the role flags in `access.ts`.
+ *
+ * Only the vocabulary lives here. How a line is serialized is not shared: phis guards against cycles
+ * and BigInt because an Add-on hands it arbitrary values, and that is its own concern.
+ */
+/** Which process wrote the record. The reader offers exactly these as filters. */
+export type PhiLogService = "phis" | "ui" | "site" | "cli";
+export type PhiLogLevel = "debug" | "info" | "warn" | "error";
+/** What a logger carries across every record it writes. */
+export type PhiLoggerContext = {
+    service: PhiLogService;
+    siteKey?: string | null;
+    area?: string | null;
+    requestId?: string | null;
+    userId?: number | string | null;
+    actorRole?: string | null;
+    pluginKey?: string | null;
+    method?: string | null;
+    path?: string | null;
+    targetType?: string | null;
+    targetId?: number | string | null;
+};
+/** What one record adds to that context. */
+export type PhiLogEvent = {
+    message?: string;
+    status?: number | null;
+    durationMs?: number | null;
+    error?: unknown;
+    meta?: Record<string, unknown>;
+};
+export interface PhiLogger {
+    readonly context: Readonly<PhiLoggerContext>;
+    child(context: Partial<PhiLoggerContext>): PhiLogger;
+    debug(event: string, data?: PhiLogEvent): void;
+    info(event: string, data?: PhiLogEvent): void;
+    warn(event: string, data?: PhiLogEvent): void;
+    error(event: string, data?: PhiLogEvent): void;
+}

package/dist/logging.js

@@ -0,0 +1,17 @@
+/**
+ * The log vocabulary phis and the site UI must both know.
+ *
+ * Two processes write these records and one of them reads all of them: a Site runtime and this server
+ * both emit structured lines to journald, and the admin log surface in phis parses them back --
+ * filtering by service, splitting by level, and projecting exactly the fields named below. The writer
+ * and the reader are therefore two ends of one format, and neither can defer to the other.
+ *
+ * They did not agree before this file existed. `service` was a closed list in both places, and the two
+ * lists drifted: phis admitted "phi-ui" while the UI wrote "phi-shared". Nothing failed. The records
+ * simply carried a name the reader never offered as a filter, so the events were there and not
+ * findable -- the same failure mode, and the same cure, as the role flags in `access.ts`.
+ *
+ * Only the vocabulary lives here. How a line is serialized is not shared: phis guards against cycles
+ * and BigInt because an Add-on hands it arbitrary values, and that is its own concern.
+ */
+export {};

package/dist/media-storage.d.ts

@@ -23,8 +23,32 @@ export type PhisMediaObjectStreamInput = {
     body: ReadableStream<Uint8Array>;
     contentType: string;
     metadata?: Record<string, string>;
+    /**
+     * Told that nobody is waiting for this write any more.
+     *
+     * A body that stops arriving does not, on its own, end the write: the Client is gone or silent while
+     * the Provider sits waiting for a byte that will never come. Core aborts the read either way, so an
+     * Adapter that ignores this still ends -- with a torn object it must clean up. Honouring it is how an
+     * Adapter stops paying for the write, and for a remote Provider that is a request in flight.
+     */
+    signal?: AbortSignal;
 };
 export type PhisMediaObjectHead = {
+    /**
+     * What this Provider can attest about the object's content, if anything.
+     *
+     * Deliberately not `etag`. An ETag is an HTTP cache validator and each Provider fills it with what it
+     * likes -- a real SHA-256 for Core's own storage, an MD5 for a single-request S3 PUT, and a digest of
+     * part digests above that, which hashes no bytes anyone uploaded. Reading one as a content hash is
+     * how an MD5 ends up recorded as a SHA-256.
+     *
+     * Null is the correct answer wherever the Provider cannot say. A missing digest is a fact Core can
+     * record; a wrong one invites a comparison that quietly finds nothing.
+     */
+    checksum?: {
+        algorithm: PhisMediaChecksumAlgorithm;
+        value: string;
+    } | null;
     storageKey: string;
     byteSize: number;
     contentType: string;
@@ -72,13 +96,118 @@ export type PhiMediaUploadPlanInput = {
      * Core owns its route table, so the address is handed to the adapter rather than assembled by it.
      */
     proxyUploadUrl: string;
+    /**
+     * What the client says it is about to send, and under which algorithm, as lowercase hex.
+     *
+     * Present only for a Profile whose probe found the endpoint verifies that algorithm: an adapter that
+     * receives it must sign it into the request and name the header the client has to send, so a body
+     * that does not match is refused there and never becomes an object. That refusal is what makes the
+     * figure trustworthy -- Core records the client's number because a wrong one would not have got this
+     * far, not because the client is believed.
+     *
+     * The algorithm travels with the value because the adapter does not get to pick one. It was settled
+     * for this Profile when it was probed, and a plan that quietly used another would produce a digest
+     * that is correct and yet incomparable with every digest recorded before it.
+     *
+     * Absent means the digest will be established some other way, which is Core hashing the body as it
+     * streams through. An adapter must never invent one.
+     */
+    checksum?: {
+        algorithm: PhisMediaChecksumAlgorithm;
+        value: string;
+    };
 };
 export type PhiMediaUploadCompletionInput = {
     storageKey: string;
     /** Whatever the plan's issuer asked the Client to bring back. Core passes it through unread. */
     completion?: unknown;
 };
+/**
+ * What one endpoint turned out to be able to do, established by trying rather than by asking.
+ *
+ * A Provider is one adapter over many backends: the S3 adapter speaks to AWS, to MinIO and to Garage,
+ * and they do not agree on everything. So the capability belongs to the configured endpoint and not to
+ * the code, and no field of the configuration would tell Core which one it is looking at.
+ *
+ * Establishing it once, when an operator sets a Profile up, also moves a whole class of failure
+ * forward: today a wrong endpoint, a missing permission or a bucket that does not exist is discovered
+ * by whoever uploads first, and reaches them as their error rather than as a misconfiguration.
+ */
+/**
+ * The digests this system knows how to record, named so what is stored says what it is.
+ *
+ * One column holding "a checksum" is how an MD5 ends up in a field called SHA-256 and nobody notices:
+ * an `ETag` is whatever a Provider decided to put there, and Providers disagree. Every recorded digest
+ * therefore carries the algorithm that produced it.
+ */
+export declare const PHIS_MEDIA_CHECKSUM_ALGORITHMS: readonly ["sha256", "sha512", "xxhash128", "crc64nvme", "crc32c", "crc32", "md5"];
+export type PhisMediaChecksumAlgorithm = (typeof PHIS_MEDIA_CHECKSUM_ALGORITHMS)[number];
+/**
+ * The digests strong enough to answer "is this the same file", rather than only "did it arrive intact".
+ *
+ * The distinction is not fussiness. CRC is linear: given a stored object, a second file colliding with
+ * it is algebra rather than computation, and MD5 collisions are a download. Both remain perfectly good
+ * evidence that a transfer was not corrupted, which is the other thing a checksum is for.
+ *
+ * What rides on this is duplicate detection, and a collision there is a refused upload rather than a
+ * substituted file -- so the cost of trusting a weak digest is that someone who may already write to a
+ * Space can stop one file from entering it. Small, but not nothing, and free to avoid.
+ */
+export declare const PHIS_MEDIA_IDENTITY_CHECKSUM_ALGORITHMS: readonly PhisMediaChecksumAlgorithm[];
+export declare function isPhisMediaIdentityChecksum(algorithm: string | null | undefined): boolean;
+/**
+ * Which of the digests an endpoint verifies a Profile will record.
+ *
+ * Chosen once, when the Profile is probed, and never per upload: duplicate detection compares digests,
+ * and two are only comparable under the same algorithm. Deterministic on purpose -- the same measured
+ * endpoint always yields the same answer, so re-probing an unchanged endpoint does not silently start a
+ * second cohort of objects that can never be told to match the first.
+ *
+ * Only identity-grade digests are eligible. A CRC an endpoint also verifies still proves a transfer
+ * intact, and Core records it when that is what arrived; it is simply not what a Profile asks for.
+ */
+export declare function choosePhisMediaChecksumAlgorithm(probe: {
+    verifiedAlgorithms: readonly PhisMediaChecksumAlgorithm[];
+} | null | undefined): PhisMediaChecksumAlgorithm | null;
+export type PhisMediaStorageProbe = {
+    /** Whether a small object could be written, read back, and removed again. */
+    writable: boolean;
+    /**
+     * Which digests the endpoint was found to check against the bytes it is given.
+     *
+     * An algorithm is listed only when a correct digest was accepted *and* a deliberately wrong one was
+     * refused. Accepting alone proves nothing: an endpoint that ignores the header accepts everything,
+     * and a checksum nobody verifies is a claim by the uploader wearing the shape of proof.
+     *
+     * What it buys is a direct upload that still yields a trustworthy digest -- the bytes go from the
+     * client to the storage without passing through Core, and the storage refuses them if they are not
+     * what the client said they were. Which of the listed algorithms is used is settled once, per
+     * Profile, rather than per upload: what is recorded has to stay comparable with what was recorded
+     * before it, and an algorithm that changes underneath splits one set of objects into two that can
+     * never be told to be the same.
+     */
+    verifiedAlgorithms: PhisMediaChecksumAlgorithm[];
+    /**
+     * Whether a digest survives an object arriving in parts.
+     *
+     * A checksum signed into one PUT covers that PUT. Above the single-request limit an object is
+     * assembled from parts, and the usual answer is a digest of the part digests -- a number that hashes
+     * no bytes anyone uploaded. An endpoint that computes over the whole assembled object instead keeps
+     * the guarantee at any size; one that does not confines it to what fits in one request.
+     */
+    verifiesWholeMultipartObject: boolean;
+    /** What did not answer, in an operator's terms. Empty when everything did. */
+    findings: string[];
+};
 export interface PhisMediaStorageAdapter {
+    /**
+     * Tries what this endpoint can do, and leaves nothing behind.
+     *
+     * Runs when a Profile is configured, not per upload. It writes a small object under a key of its own
+     * and removes it again; a Provider that cannot be probed answers with `writable: false` and a finding
+     * rather than throwing, because a Profile that cannot be reached is an answer too.
+     */
+    probeCapabilities(): Promise<PhisMediaStorageProbe>;
     putObject(input: PhisMediaObjectInput): Promise<PhisMediaObjectHead>;
     putObjectStream(input: PhisMediaObjectStreamInput): Promise<PhisMediaObjectHead>;
     getObject(storageKey: string): Promise<Buffer | null>;

package/dist/media-storage.js

@@ -7,3 +7,59 @@
  * and answers about objects.
  */
 export const PHI_LOCAL_MEDIA_STORAGE_PROVIDER_ID = "@phis/server/storage-local";
+/**
+ * What one endpoint turned out to be able to do, established by trying rather than by asking.
+ *
+ * A Provider is one adapter over many backends: the S3 adapter speaks to AWS, to MinIO and to Garage,
+ * and they do not agree on everything. So the capability belongs to the configured endpoint and not to
+ * the code, and no field of the configuration would tell Core which one it is looking at.
+ *
+ * Establishing it once, when an operator sets a Profile up, also moves a whole class of failure
+ * forward: today a wrong endpoint, a missing permission or a bucket that does not exist is discovered
+ * by whoever uploads first, and reaches them as their error rather than as a misconfiguration.
+ */
+/**
+ * The digests this system knows how to record, named so what is stored says what it is.
+ *
+ * One column holding "a checksum" is how an MD5 ends up in a field called SHA-256 and nobody notices:
+ * an `ETag` is whatever a Provider decided to put there, and Providers disagree. Every recorded digest
+ * therefore carries the algorithm that produced it.
+ */
+export const PHIS_MEDIA_CHECKSUM_ALGORITHMS = [
+    "sha256", "sha512", "xxhash128", "crc64nvme", "crc32c", "crc32", "md5",
+];
+/**
+ * The digests strong enough to answer "is this the same file", rather than only "did it arrive intact".
+ *
+ * The distinction is not fussiness. CRC is linear: given a stored object, a second file colliding with
+ * it is algebra rather than computation, and MD5 collisions are a download. Both remain perfectly good
+ * evidence that a transfer was not corrupted, which is the other thing a checksum is for.
+ *
+ * What rides on this is duplicate detection, and a collision there is a refused upload rather than a
+ * substituted file -- so the cost of trusting a weak digest is that someone who may already write to a
+ * Space can stop one file from entering it. Small, but not nothing, and free to avoid.
+ */
+export const PHIS_MEDIA_IDENTITY_CHECKSUM_ALGORITHMS = ["sha256", "sha512"];
+export function isPhisMediaIdentityChecksum(algorithm) {
+    return PHIS_MEDIA_IDENTITY_CHECKSUM_ALGORITHMS.includes(algorithm);
+}
+/**
+ * Which of the digests an endpoint verifies a Profile will record.
+ *
+ * Chosen once, when the Profile is probed, and never per upload: duplicate detection compares digests,
+ * and two are only comparable under the same algorithm. Deterministic on purpose -- the same measured
+ * endpoint always yields the same answer, so re-probing an unchanged endpoint does not silently start a
+ * second cohort of objects that can never be told to match the first.
+ *
+ * Only identity-grade digests are eligible. A CRC an endpoint also verifies still proves a transfer
+ * intact, and Core records it when that is what arrived; it is simply not what a Profile asks for.
+ */
+export function choosePhisMediaChecksumAlgorithm(probe) {
+    if (!probe)
+        return null;
+    for (const candidate of PHIS_MEDIA_IDENTITY_CHECKSUM_ALGORITHMS) {
+        if (probe.verifiedAlgorithms.includes(candidate))
+            return candidate;
+    }
+    return null;
+}

package/dist/media.d.ts

@@ -0,0 +1,228 @@
+/**
+ * How a Media Space names its kind on the wire.
+ *
+ * Only the name is shared. phis stores the kind as a smallint and that number is its own business --
+ * the site UI never sees it, so putting it here would place a storage detail in a contract.
+ *
+ * What made this worth writing down is that the translation between the two was incomplete: phis knew
+ * four kinds and mapped three, falling back to `"site"` for the rest, while the UI declared its own
+ * union of the same three. An Add-on Space therefore reached the administration surface calling itself
+ * a Site Space, in the one view that shows Add-on Spaces at all. With the names here, the map on the
+ * server side is a total function from its own enum onto this one, and a kind that is added and not
+ * mapped stops compiling.
+ */
+export declare const PHI_MEDIA_SPACE_KINDS: readonly ["site", "user", "group", "addon"];
+export type PhiMediaSpaceKind = (typeof PHI_MEDIA_SPACE_KINDS)[number];
+/**
+ * The kinds a Module may declare a need for.
+ *
+ * The Site Space always exists and is governed by the Core Media role matrix, so declaring it could
+ * only repeat what is already true. An Add-on Space belongs to its Add-on and comes with installing
+ * it, rather than being asked for by a Module.
+ */
+export declare const PHI_DECLARABLE_MEDIA_SPACE_KINDS: readonly ["user", "group"];
+export type PhiDeclarableMediaSpaceKind = (typeof PHI_DECLARABLE_MEDIA_SPACE_KINDS)[number];
+export declare function isPhiDeclarableMediaSpaceKind(value: unknown): value is PhiDeclarableMediaSpaceKind;
+/**
+ * The display properties an Asset may carry, as bits of `media_assets.presentation_flags`.
+ *
+ * Shared because the number itself travels: the site UI sends a mask as a list filter and an array of
+ * these values when metadata is saved, and phis both answers the filter with `flags & mask <> 0` and
+ * refuses a value it does not know. Two sides that must agree on a number is what this package is for,
+ * and the copy that lived on each side had already drifted -- phis still carried `Private`, `Archived`
+ * and `Restricted` long after lifecycle and delivery had become columns of their own.
+ *
+ * Display only. Access is `delivery_policy` and `lifecycle_status`, never a bit in here.
+ *
+ * Bits 1 and 2 are free, and before v1 a bit may be given a new meaning rather than kept vacant.
+ */
+export declare const PhiMediaAssetFlags: {
+    /** Offered as a background. What an Asset is for; where it came from is `meta.source`. */
+    readonly Background: number;
+    readonly Featured: number;
+    readonly Locked: number;
+    readonly Mask: number;
+};
+export type PhiMediaAssetFlag = (typeof PhiMediaAssetFlags)[keyof typeof PhiMediaAssetFlags];
+/**
+ * The rest of the Media vocabulary both sides speak.
+ *
+ * Kind names travel as `kind` in the list contract and are stored on the Asset; Folder flags travel in
+ * the Folder payload; a variant key is a number in a delivery URL and the name phis generates the
+ * rendition under. None of it is one side's private business, and all of it stood twice -- once here in
+ * spirit, once in each repository in fact -- until a bit value drifted and showed what that costs.
+ *
+ * The two resolvers come along because a vocabulary without its total function is only half a contract:
+ * a content type must land on the same kind in the browser and on the server, or an upload is filed as
+ * one thing and listed as another.
+ */
+export declare const PhiMediaFolderFlags: {
+    readonly Collapsed: number;
+    readonly Hidden: number;
+    readonly Locked: number;
+};
+export declare const PhiMediaKind: {
+    readonly Image: "image";
+    readonly Video: "video";
+    readonly Audio: "audio";
+    readonly Pdf: "pdf";
+    readonly Markdown: "markdown";
+    readonly Document: "document";
+    readonly Archive: "archive";
+    readonly Font: "font";
+    readonly Binary: "binary";
+    readonly Other: "other";
+};
+export declare const PhiImageAssetVariantKey: {
+    readonly Thumbnail: 0;
+    readonly Preview: 1;
+    readonly Banner: 2;
+    readonly Header: 3;
+    readonly Card: 4;
+    readonly Hero: 5;
+    readonly Avatar: 6;
+    readonly Logo: 7;
+    readonly Landscape: 8;
+    readonly Portrait: 9;
+};
+export declare const PhiImageAssetVariantKeyName: {
+    readonly 0: "thumbnail";
+    readonly 1: "preview";
+    readonly 2: "banner";
+    readonly 3: "header";
+    readonly 4: "card";
+    readonly 5: "hero";
+    readonly 6: "avatar";
+    readonly 7: "logo";
+    readonly 8: "landscape";
+    readonly 9: "portrait";
+};
+export type PhiImageAssetVariantSpec = {
+    width: number;
+    height: number;
+    fit: "cover" | "contain";
+    quality: number;
+    format: "webp";
+};
+export declare function normalizePhiMediaKind(kind: string | null | undefined): "binary" | "other" | "image" | "video" | "audio" | "pdf" | "markdown" | "document" | "archive" | "font";
+export declare function resolvePhiMediaKindFromContentType(contentType: string | null | undefined): "binary" | "other" | "image" | "video" | "audio" | "pdf" | "markdown" | "document" | "archive" | "font";
+export declare function normalizePhiImageAssetVariantKey(key: unknown): 0 | 1 | 2 | 3 | 4 | 5 | 6 | 9 | 7 | 8 | null;
+export declare function resolvePhiImageAssetVariantKeyName(key: number | null | undefined): string | null;
+export declare function resolvePhiImageAssetVariantSpec(key: number | null | undefined): PhiImageAssetVariantSpec | null;
+/**
+ * The two closed vocabularies that decide whether an Asset may be delivered at all.
+ *
+ * The numbers themselves reach the site UI: an Asset's detail payload carries `lifecycleStatus` and
+ * `deliveryPolicy` as they stand in the row, and the UI decides from them whether `next/image` may be
+ * pointed at the original. phis evaluates `delivery_policy` before any physical lookup, so a value that
+ * means one thing on one side and another on the other would be a visibility bug, not a display bug.
+ *
+ * Unlike the Space kind next to them in phis, which stays a storage detail because the wire carries its
+ * name instead of its number.
+ */
+export declare const PhiMediaLifecycleStatus: {
+    readonly Pending: 1;
+    readonly Ready: 2;
+    readonly Archived: 3;
+    readonly Quarantined: 4;
+    readonly Failed: 5;
+};
+export declare const PhiMediaDeliveryPolicy: {
+    readonly Public: 1;
+    readonly Authenticated: 2;
+    readonly User: 3;
+    readonly Group: 4;
+    readonly Internal: 5;
+};
+/**
+ * What a typeface says about its own proportions.
+ *
+ * Shared because the numbers cross: phis reads them out of the uploaded file once and keeps them on the
+ * Asset, and the site UI turns them into the `size-adjust` and `*-override` descriptors of a fallback
+ * `@font-face`. Without that face a browser sets the page in a local substitute and reflows when the
+ * real file lands, which is the one thing a viewer actually sees.
+ *
+ * Everything is in font units on the `unitsPerEm` grid, so a reader divides rather than assumes 1000.
+ */
+export type PhiFontMetrics = {
+    /** The container the numbers were read from. */
+    format: "sfnt" | "woff" | "woff2";
+    familyName: string | null;
+    unitsPerEm: number;
+    ascent: number;
+    descent: number;
+    lineGap: number;
+    capHeight: number | null;
+    xHeight: number | null;
+    /**
+     * How wide running text sets, as an advance width.
+     *
+     * `glyphs` is the frequency-weighted advance of the characters prose is made of. `os2` is the font's
+     * own `xAvgCharWidth`, which averages every glyph in the file and is therefore wrong for a Latin page
+     * in a family that also carries Greek -- the source travels so a reader can tell the two apart.
+     */
+    xWidthAvg: number | null;
+    xWidthAvgSource: "glyphs" | "os2" | null;
+    /**
+     * What the file classifies itself as, and `null` where it classifies itself as nothing.
+     *
+     * Plenty of good fonts leave both PANOSE and the `OS/2` family class empty, so the absence is a fact
+     * about the file rather than a reason to guess: whoever picks the local substitute decides instead.
+     */
+    category: "serif" | "sans-serif" | "monospace" | null;
+    /**
+     * Which unicode cuts the typeface has characters in, read out of its `cmap` at upload.
+     *
+     * Absent on a font uploaded before cuts existed; such a font is delivered whole.
+     */
+    coverage?: PhiFontCoverage | null;
+};
+/**
+ * The cuts a typeface can be delivered in.
+ *
+ * The number stands in a delivery URL, so it is shared; the named cuts follow the unicode ranges Google
+ * Fonts divides its families along, so a face declared here splits where fonts are commonly split.
+ * `Rest` is not a range but everything a typeface has outside all of them -- its own characters, listed
+ * per font in `PhiFontCoverage.restRanges`, so a page never loses a glyph and never fetches a cut for a
+ * character the font does not have.
+ */
+export declare const PhiFontSubsetKey: {
+    readonly Latin: 0;
+    readonly LatinExt: 1;
+    readonly Cyrillic: 2;
+    readonly CyrillicExt: 3;
+    readonly Greek: 4;
+    readonly GreekExt: 5;
+    readonly Vietnamese: 6;
+    readonly Math: 7;
+    readonly Symbols: 8;
+    readonly Rest: 15;
+};
+export type PhiFontSubsetKeyValue = (typeof PhiFontSubsetKey)[keyof typeof PhiFontSubsetKey];
+/** An inclusive codepoint range. */
+export type PhiUnicodeRange = readonly [start: number, end: number];
+/**
+ * Raised whenever the ranges below or the way a cut is produced changes, so every stored cut is made
+ * again rather than served under a rule that no longer describes it.
+ */
+export declare const PHI_FONT_SUBSET_VERSION = 1;
+/** The named cuts, as Google Fonts' CSS2 API states them for a Latin, Cyrillic and Greek family. */
+export declare const PHI_FONT_SUBSET_RANGES: Readonly<Record<Exclude<PhiFontSubsetKeyValue, 15>, readonly PhiUnicodeRange[]>>;
+/** What a typeface has characters in: the named cuts, and its own characters outside all of them. */
+export type PhiFontCoverage = {
+    subsets: PhiFontSubsetKeyValue[];
+    restRanges: PhiUnicodeRange[];
+};
+export declare function isPhiCodepointInRanges(codepoint: number, ranges: readonly PhiUnicodeRange[]): boolean;
+/** A `unicode-range` descriptor value. */
+export declare function formatPhiUnicodeRange(ranges: readonly PhiUnicodeRange[]): string;
+/** The ranges a cut covers for one typeface: the shared list for a named cut, the font's own for `Rest`. */
+export declare function resolvePhiFontSubsetRanges(key: PhiFontSubsetKeyValue, coverage: PhiFontCoverage): readonly PhiUnicodeRange[];
+export declare function isPhiFontSubsetKey(value: unknown): value is PhiFontSubsetKeyValue;
+/**
+ * The cuts to preload for a page in `locale`, `Latin` first, restricted to what the font covers.
+ *
+ * `locale` is a BCP 47 tag; its script subtag overrides the language's usual one, so `sr-Latn` preloads
+ * `LatinExt` where `sr` preloads `Cyrillic`.
+ */
+export declare function resolvePhiFontPreloadSubsetKeys(locale: string | null | undefined, coverage: PhiFontCoverage): PhiFontSubsetKeyValue[];