@phis/contracts 0.3.1 → 0.5.0

package/dist/media-storage.d.ts

@@ -33,6 +33,20 @@ export type PhisMediaObjectStreamInput = {
      */
     signal?: AbortSignal;
 };
+/** Which bytes of an object somebody wants: the first one, and how many. */
+export type PhisMediaObjectRange = {
+    /** The first byte, counted from zero and inside the object. */
+    offset: number;
+    /** How many bytes are wanted. An implementation may serve fewer, and then says so. */
+    length: number;
+};
+export type PhisMediaObjectRangeStream = {
+    body: ReadableStream<Uint8Array>;
+    /** What was served, which is what a `Content-Range` may claim -- never merely what was asked for. */
+    range: PhisMediaObjectRange;
+    /** The object's whole size, so a `Content-Range` can name the total it is a part of. */
+    byteSize: number;
+};
 export type PhisMediaObjectHead = {
     /**
      * What this Provider can attest about the object's content, if anything.
@@ -82,6 +96,34 @@ export type PhiMediaUploadPlan = {
     method: "PUT";
     headers: Record<string, string>;
     expiresAt: string;
+} | {
+    /**
+     * The body in several requests, assembled by the Provider.
+     *
+     * What this buys is not a larger ceiling but a resumable one. A single request that fails at ninety
+     * per cent has to be sent again from the first byte, and above a few hundred megabytes on an
+     * ordinary connection that is the usual outcome rather than the unlucky one. Each part here fails
+     * and repeats on its own.
+     *
+     * The parts are in order and each covers `partSizeBytes`, except the last, which covers what is
+     * left. That is the whole addressing scheme: part *n* is the bytes from `(n - 1) * partSizeBytes`,
+     * and a Client that can slice a file needs nothing else.
+     *
+     * `uploadId` travels out and comes back. The Client returns it, with each part's entity tag, as the
+     * `completion` that `completeUpload` assembles from -- and Core keeps its own copy, because the one
+     * thing a Client cannot be asked to do is report an upload it has stopped existing to report.
+     */
+    kind: "multipart-put";
+    method: "PUT";
+    uploadId: string;
+    partSizeBytes: number;
+    parts: readonly {
+        /** One-based and contiguous, the way every part API counts. */
+        partNumber: number;
+        url: string;
+        headers?: Record<string, string>;
+    }[];
+    expiresAt: string;
 };
 export type PhiMediaUploadPlanKindKey = PhiMediaUploadPlan["kind"];
 export type PhiMediaUploadPlanInput = {
@@ -100,10 +142,13 @@ export type PhiMediaUploadPlanInput = {
      * 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.
+     * receives it must sign it into the request, 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.
+     *
+     * Signed, and not also named as a header for the Client to repeat. Signing a request that has no body
+     * yet puts the digest in the query string, where the signature covers it; a checksum header outside the
+     * signed set is refused by a strict endpoint, so naming it costs the upload instead of securing it.
      *
      * 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
@@ -116,6 +161,113 @@ export type PhiMediaUploadPlanInput = {
         algorithm: PhisMediaChecksumAlgorithm;
         value: string;
     };
+    /**
+     * One digest per part, in part order, as lowercase hex, for a body that is to arrive in parts.
+     *
+     * The same bargain as `checksum` and for the same reason, one level down: each part's digest is signed
+     * into that part's request, so a part whose bytes do not match is refused and never joins the object.
+     * Present only together with `mayAssembleFromParts`, and only where the Profile's base algorithm is
+     * SHA-256 -- these are SHA-256 digests and an adapter must not offer them under another name.
+     *
+     * The divisions are `resolvePhiMediaUploadPartSizeBytes` over the same `sizeBytes`, which is how the
+     * Client could compute them before this plan existed. An adapter that receives a count not matching that
+     * rule must refuse the plan rather than address the parts it was given: the mismatch means the two sides
+     * divided the body differently, and every digest after the first would be signed against other bytes.
+     *
+     * `checksum` alongside this carries the composite these add up to, which is what Core records. The
+     * adapter does not need it and must not recompute it.
+     */
+    partChecksums?: readonly string[];
+    /**
+     * Whether this Profile may answer with an object assembled from parts.
+     *
+     * Core's decision and not the Provider's, for the same reason `checksum` above is: a Provider does not
+     * get to grade its own endpoint. What Core weighs is the size -- a single request that fails at ninety
+     * per cent is sent again from the first byte, and above a few hundred megabytes that is the usual
+     * outcome -- against what the object will be able to attest afterwards.
+     *
+     * It is a permission and not a capability: the Provider may be perfectly able and still not be asked.
+     *
+     * Absent means no. A Provider that cannot assemble parts ignores it either way.
+     */
+    mayAssembleFromParts?: boolean;
+};
+/**
+ * What is needed to carry on delivering an assembly that was already opened.
+ *
+ * The case is a page that went away mid-upload -- a reload, a crash, a tab somebody closed. The parts that
+ * did arrive are at the Provider, paid for and perfectly good, and until now the only thing that could
+ * happen to them was to be aborted: the plan was gone with the page, and asking for a new one opens a
+ * second assembly the first one's parts do not belong to. Which is why this is not `createUploadPlan` with
+ * an extra field. `createUploadPlan` *opens* an upload; this one joins the one that is open.
+ *
+ * It is deliberately not "list the parts and let Core sign what is missing": which parts an assembly holds
+ * and which addresses those parts have are the same Provider's business, and splitting them would put Core
+ * in the position of deciding what is missing from a listing it cannot interpret.
+ *
+ * `partChecksums` carries **every** part's digest, in part order, exactly as `createUploadPlan` received it
+ * -- the implementation signs the ones it is about to ask for. Anything else would make Core work out the
+ * gap before it knows what the gap is.
+ */
+export type PhiMediaUploadResumeInput = {
+    storageKey: string;
+    /** The Provider's own name for the assembly, which the session kept because the Client could not. */
+    uploadId: string;
+    contentType: string;
+    sizeBytes: number;
+    expiresAt: string;
+    /** One digest per part, in part order, as lowercase hex. The same bargain as on a fresh plan. */
+    partChecksums?: readonly string[];
+};
+/**
+ * An assembly as it stands: what is still to be sent, and what is already there.
+ *
+ * The two halves travel together because a completion has to name every part. The Client brings back the
+ * tags of the parts it sent, and these are the tags of the parts an earlier page sent -- nobody else has
+ * them, and the Client that had them is the thing that went away.
+ */
+export type PhiMediaUploadResumption = {
+    /** Addresses for the parts the storage does not hold yet. Empty where the body is complete. */
+    plan: Extract<PhiMediaUploadPlan, {
+        kind: "multipart-put";
+    }>;
+    /** The parts it does hold, in part order. */
+    uploaded: readonly {
+        partNumber: number;
+        /** As the storage reports it, quoting and all: a completion has to name it exactly. */
+        eTag: string;
+        sizeBytes: number;
+    }[];
+};
+/**
+ * What a storage is asked to clean up on its own, and how long it must wait first.
+ *
+ * Both figures follow from how long an upload session may live, which is Core's to know. They are days
+ * because that is the only unit an object lifecycle rule takes, and they are more than one day because such
+ * a rule is evaluated asynchronously -- a rule of "one day" can fire on an upload that still has hours to
+ * run, and aborting a body somebody is in the middle of sending is worse than paying for it a while longer.
+ *
+ * `stagingKeyPrefixes` are Core's key space, without whatever prefix a Provider adds of its own; the
+ * Provider prepends that the same way it does for an object key.
+ *
+ * **An empty prefix list means no expiry rule at all, and an implementation must treat it that way.** An
+ * expiry rule matching everything would delete every object in the storage after two days, which is the one
+ * mistake in this area that cannot be undone -- so "expire nothing" and "expire everything" must never be
+ * the same argument.
+ */
+export type PhisMediaLifecyclePolicy = {
+    /**
+     * Days after an upload was started before the storage may abort what was never completed.
+     *
+     * This is the whole reason the rule exists. A Client that reports its own failure is handled without any
+     * of this, and one that crashes, loses its connection or has its tab killed reports nothing -- and what it
+     * leaves behind is parts that are paid for and cannot be listed.
+     */
+    abortIncompleteMultipartUploadAfterDays: number;
+    /** Key prefixes, in Core's key space, under which a body is staged before it becomes an Asset. */
+    stagingKeyPrefixes: readonly string[];
+    /** Days a staged object may sit under those prefixes before the storage removes it. */
+    expireStagedObjectsAfterDays: number;
 };
 export type PhiMediaUploadCompletionInput = {
     storageKey: string;
@@ -140,8 +292,9 @@ export type PhiMediaUploadCompletionInput = {
  * 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 declare const PHIS_MEDIA_CHECKSUM_ALGORITHMS: readonly ["sha256", "sha512", "sha256-composite", "xxhash128", "crc64nvme", "crc32c", "crc32", "md5"];
 export type PhisMediaChecksumAlgorithm = (typeof PHIS_MEDIA_CHECKSUM_ALGORITHMS)[number];
+export { PHIS_MEDIA_UPLOAD_MAX_PART_COUNT, PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES, formatPhiMediaCompositeChecksum, parsePhiMediaCompositeChecksum, resolvePhiMediaUploadPartCount, resolvePhiMediaUploadPartSizeBytes, } from "./media.js";
 /**
  * The digests strong enough to answer "is this the same file", rather than only "did it arrive intact".
  *
@@ -154,6 +307,19 @@ export type PhisMediaChecksumAlgorithm = (typeof PHIS_MEDIA_CHECKSUM_ALGORITHMS)
  * 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[];
+/**
+ * Why `sha256-composite` is identity-grade although it hashes digests rather than bytes.
+ *
+ * It is `SHA256` over the concatenated part digests of a body divided by a fixed rule. For the question
+ * duplicate detection asks -- are these the same bytes -- it is as hard to forge as SHA-256 itself: a
+ * second file matching one requires a SHA-256 collision in some part. What it cannot do is compare across
+ * divisions, which is why the division is written into the value and why the rule above is frozen.
+ *
+ * It exists because a browser cannot produce the other kind for a large file. Web Crypto has no
+ * incremental digest, so a whole-object SHA-256 means holding the entire body in memory; a part digest is
+ * one part, and the composite over those is a few kilobytes. The choice is not between this and a
+ * whole-object digest, it is between this and no digest at all.
+ */
 export declare function isPhisMediaIdentityChecksum(algorithm: string | null | undefined): boolean;
 /**
  * Which of the digests an endpoint verifies a Profile will record.
@@ -165,6 +331,10 @@ export declare function isPhisMediaIdentityChecksum(algorithm: string | null | u
  *
  * 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.
+ *
+ * `sha256-composite` is not eligible either, for a different reason: it is not something an endpoint
+ * verifies, it is the form a SHA-256 takes when a body arrived in parts. A Profile records a base
+ * algorithm, and an object assembled from parts under a `sha256` Profile carries the composite of it.
  */
 export declare function choosePhisMediaChecksumAlgorithm(probe: {
     verifiedAlgorithms: readonly PhisMediaChecksumAlgorithm[];
@@ -187,15 +357,6 @@ export type PhisMediaStorageProbe = {
      * 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[];
 };
@@ -210,7 +371,46 @@ export interface PhisMediaStorageAdapter {
     probeCapabilities(): Promise<PhisMediaStorageProbe>;
     putObject(input: PhisMediaObjectInput): Promise<PhisMediaObjectHead>;
     putObjectStream(input: PhisMediaObjectStreamInput): Promise<PhisMediaObjectHead>;
+    /**
+     * The whole object at once, for code that has to look at every byte.
+     *
+     * Image processing, font subsetting and content sniffing are what this is for: they hold the bytes
+     * because they read them, and no stream would change that. Serving an object to somebody is not one
+     * of those cases -- see `getObjectStream`.
+     */
     getObject(storageKey: string): Promise<Buffer | null>;
+    /**
+     * The object as it arrives, for code that only passes it on.
+     *
+     * Delivery reads nothing: it copies bytes from the Provider to whoever asked, and holding the whole
+     * object to do that makes the largest object a Site accepts the amount of memory one download costs.
+     * A Provider that stores remotely hands back its own response body, and the Local adapter a file read
+     * stream, so nothing between the two ever holds more than what is in flight.
+     *
+     * `null` means the object is not there, the same answer `getObject` gives.
+     */
+    getObjectStream(storageKey: string): Promise<ReadableStream<Uint8Array> | null>;
+    /**
+     * Part of an object as it arrives, for serving a `Range` request.
+     *
+     * What this is for is seeking. A browser asked for a video cannot start in the middle without it, and
+     * Safari commonly declines to play at all where a server answers `200` to a `Range` -- so delivery
+     * without this is delivery of files people download, not of media people scrub through.
+     *
+     * It reports the range it **actually** produced rather than echoing the one it was given, and that is
+     * the point of the shape. A `Content-Range` is a claim about bytes; a Provider that quietly ignored the
+     * request and returned the whole object would otherwise turn that claim into a lie, and the caller
+     * would frame a complete body as a partial one. Comparing what was asked with what came back is what
+     * lets delivery answer `200` in that case instead.
+     *
+     * `offset` is the first byte, `length` is how many are wanted. An implementation clamps `length` to the
+     * end of the object and says so in what it returns; the caller has already established that the offset
+     * is inside the object, because it knows the size and a range beyond it is a `416` rather than a read.
+     * A `length` of zero -- asked for, or left after clamping -- is an empty body and not an error.
+     *
+     * `null` means the object is not there, the same answer `getObjectStream` gives.
+     */
+    getObjectRangeStream(storageKey: string, range: PhisMediaObjectRange): Promise<PhisMediaObjectRangeStream | null>;
     /**
      * The first bytes of an object, for deciding what it actually is without moving it.
      *
@@ -237,6 +437,29 @@ export interface PhisMediaStorageAdapter {
     listPrefix(prefix: string): Promise<PhisMediaObjectHead[]>;
     /** States how the Client is to deliver this body. */
     createUploadPlan(input: PhiMediaUploadPlanInput): Promise<PhiMediaUploadPlan>;
+    /**
+     * Says how what is left of an already opened assembly is to be delivered.
+     *
+     * This is what makes a large upload survive the page it was started from. A part that fails repeats
+     * alone already, but a reload used to cost every part that had arrived -- the plan lived in the tab and
+     * the parts were aborted the moment the page said it was leaving. The parts are the expensive thing;
+     * they are at the Provider and nothing is wrong with them.
+     *
+     * The Provider answers, not Core, because only the Provider knows what it is holding. A Client's account
+     * of how far it got is a claim about a session that has stopped existing, and a Core-side tally would be
+     * a second record of the same fact that can disagree with the storage.
+     *
+     * `null` means there is nothing to carry on: the assembly was aborted, or a lifecycle rule has reached
+     * it, or it was never this storage's. It also means that for a Provider that never assembles anything --
+     * a no-op answer and not a shortcoming, the same way `applyCorsPolicy` is a no-op where no browser ever
+     * addresses the storage.
+     *
+     * An implementation must refuse -- `null` -- where what it holds was divided differently from what it is
+     * being asked to sign: a part of the wrong size means the object would assemble into something other
+     * than the body Core recorded a digest for, and finishing it would put a correct digest on the wrong
+     * bytes. Starting over is the honest outcome there.
+     */
+    resumeUploadPlan(input: PhiMediaUploadResumeInput): Promise<PhiMediaUploadResumption | null>;
     /**
      * Settles the staged object once the Client says it is done, and answers what actually landed.
      *
@@ -256,6 +479,25 @@ export interface PhisMediaStorageAdapter {
      * to check, because a Provider that cannot say no to a body it never receives has nothing to say.
      */
     applyCorsPolicy(origins: readonly string[]): Promise<void>;
+    /**
+     * States what the storage is to clean up by itself, because Core cannot see it and never will.
+     *
+     * The reason this is not a sweeper is that the two things it names are invisible to the side that would
+     * have to sweep them. An unfinished multipart upload is billed from the moment it opens and appears in no
+     * object listing at all: only the storage knows it exists, and only the Client that has gone away could
+     * have named it. A staged object whose session expired is findable, but reaching it means opening
+     * Providers on behalf of sessions a request has no business touching -- which is why expiry deliberately
+     * releases the reservation and leaves storage alone.
+     *
+     * So the rule is written once, when a Profile is written, exactly as the CORS rule is. What Core knows is
+     * how long an upload may take and which keys are staging; what the storage knows is how to express "stop
+     * paying for this".
+     *
+     * Replaced whole, never merged, for the same reason CORS is: a rule has to state what is true now rather
+     * than accumulate what once was. A Provider with no such notion, such as the Local one, implements it as
+     * a no-op -- its files are Core's own and an operator command is what removes them.
+     */
+    applyLifecyclePolicy(policy: PhisMediaLifecyclePolicy): Promise<void>;
     /**
      * What makes two Storage Profiles the same physical storage.
      *

package/dist/media-storage.js

@@ -26,8 +26,17 @@ export const PHI_LOCAL_MEDIA_STORAGE_PROVIDER_ID = "@phis/server/storage-local";
  * therefore carries the algorithm that produced it.
  */
 export const PHIS_MEDIA_CHECKSUM_ALGORITHMS = [
-    "sha256", "sha512", "xxhash128", "crc64nvme", "crc32c", "crc32", "md5",
+    "sha256", "sha512", "sha256-composite", "xxhash128", "crc64nvme", "crc32c", "crc32", "md5",
 ];
+/*
+ * The division and the composite's recorded form live in `./media.ts`, and are re-exported here.
+ *
+ * They are the one part of this contract a browser has to compute as well: the Client hashes the parts
+ * before a plan exists, because a part digest can only be signed into a part request if it is known when
+ * that request is signed. So the rule cannot sit behind the Add-on surface, and it must not be written
+ * twice -- two copies of a division are two divisions the day one of them is edited.
+ */
+export { PHIS_MEDIA_UPLOAD_MAX_PART_COUNT, PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES, formatPhiMediaCompositeChecksum, parsePhiMediaCompositeChecksum, resolvePhiMediaUploadPartCount, resolvePhiMediaUploadPartSizeBytes, } from "./media.js";
 /**
  * The digests strong enough to answer "is this the same file", rather than only "did it arrive intact".
  *
@@ -39,7 +48,20 @@ export const PHIS_MEDIA_CHECKSUM_ALGORITHMS = [
  * 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 const PHIS_MEDIA_IDENTITY_CHECKSUM_ALGORITHMS = ["sha256", "sha512", "sha256-composite"];
+/**
+ * Why `sha256-composite` is identity-grade although it hashes digests rather than bytes.
+ *
+ * It is `SHA256` over the concatenated part digests of a body divided by a fixed rule. For the question
+ * duplicate detection asks -- are these the same bytes -- it is as hard to forge as SHA-256 itself: a
+ * second file matching one requires a SHA-256 collision in some part. What it cannot do is compare across
+ * divisions, which is why the division is written into the value and why the rule above is frozen.
+ *
+ * It exists because a browser cannot produce the other kind for a large file. Web Crypto has no
+ * incremental digest, so a whole-object SHA-256 means holding the entire body in memory; a part digest is
+ * one part, and the composite over those is a few kilobytes. The choice is not between this and a
+ * whole-object digest, it is between this and no digest at all.
+ */
 export function isPhisMediaIdentityChecksum(algorithm) {
     return PHIS_MEDIA_IDENTITY_CHECKSUM_ALGORITHMS.includes(algorithm);
 }
@@ -53,11 +75,17 @@ export function isPhisMediaIdentityChecksum(algorithm) {
  *
  * 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.
+ *
+ * `sha256-composite` is not eligible either, for a different reason: it is not something an endpoint
+ * verifies, it is the form a SHA-256 takes when a body arrived in parts. A Profile records a base
+ * algorithm, and an object assembled from parts under a `sha256` Profile carries the composite of it.
  */
 export function choosePhisMediaChecksumAlgorithm(probe) {
     if (!probe)
         return null;
     for (const candidate of PHIS_MEDIA_IDENTITY_CHECKSUM_ALGORITHMS) {
+        if (candidate === "sha256-composite")
+            continue;
         if (probe.verifiedAlgorithms.includes(candidate))
             return candidate;
     }

package/dist/media.d.ts

@@ -104,9 +104,9 @@ export type PhiImageAssetVariantSpec = {
     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 normalizePhiMediaKind(kind: string | null | undefined): "image" | "video" | "audio" | "pdf" | "markdown" | "document" | "archive" | "font" | "binary" | "other";
+export declare function resolvePhiMediaKindFromContentType(contentType: string | null | undefined): "image" | "video" | "audio" | "pdf" | "markdown" | "document" | "archive" | "font" | "binary" | "other";
+export declare function normalizePhiImageAssetVariantKey(key: unknown): 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 9 | 8 | null;
 export declare function resolvePhiImageAssetVariantKeyName(key: number | null | undefined): string | null;
 export declare function resolvePhiImageAssetVariantSpec(key: number | null | undefined): PhiImageAssetVariantSpec | null;
 /**
@@ -226,3 +226,47 @@ export declare function isPhiFontSubsetKey(value: unknown): value is PhiFontSubs
  * `LatinExt` where `sr` preloads `Cyrillic`.
  */
 export declare function resolvePhiFontPreloadSubsetKeys(locale: string | null | undefined, coverage: PhiFontCoverage): PhiFontSubsetKeyValue[];
+/**
+ * How a body above one part is divided, as a rule rather than as a Provider's private arithmetic.
+ *
+ * It lives here because two parties have to agree on it and neither can be told by the other in time. The
+ * Provider needs the part size to sign one request per part; the Client needs it *before* the plan exists,
+ * because a digest can only be signed into a request if it is known when the request is signed -- so the
+ * Client has to hash the same divisions the Provider is about to address. A rule both compute from the
+ * byte size is the only arrangement where that holds without an extra round trip.
+ *
+ * **Frozen once objects exist under it.** A `sha256-composite` value is a digest of part digests, so it
+ * answers "the same bytes divided the same way". Change the division and the same file yields a different
+ * value, which splits duplicate detection into cohorts that can never match across the change. The value
+ * carries the part size for exactly this reason: a changed rule produces non-matches, never false matches.
+ * Changing it is therefore a decision about the whole corpus, not a tuning knob.
+ *
+ * `PHIS_MEDIA_UPLOAD_MAX_PART_COUNT` is well under S3's ten thousand on purpose. Every part is signed up
+ * front, so the count is also the size of the plan a Client receives and Core holds in memory.
+ */
+export declare const PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES: number;
+export declare const PHIS_MEDIA_UPLOAD_MAX_PART_COUNT = 1000;
+/**
+ * The part size for one body, and the same answer wherever it is asked.
+ *
+ * Sixteen mebibytes until that would need more parts than are allowed, and from there the smallest whole
+ * mebibyte that fits the body into the allowance. Whole mebibytes keep the number short where it is
+ * recorded and keep the arithmetic exact in a browser, where sizes are doubles.
+ */
+export declare function resolvePhiMediaUploadPartSizeBytes(sizeBytes: number): number;
+/** How many parts one body is divided into under `resolvePhiMediaUploadPartSizeBytes`. */
+export declare function resolvePhiMediaUploadPartCount(sizeBytes: number): number;
+/**
+ * The recorded form of a `sha256-composite` digest: the digest, the part count, the part size.
+ *
+ * Duplicate detection compares these values as strings, so everything that decides whether two of them
+ * mean the same thing has to be inside the string. The digest alone would not: the same bytes divided
+ * differently hash differently, and a value that did not say how it was divided would look like a plain
+ * SHA-256 that simply failed to match. Naming the division makes a mismatch legible instead of puzzling.
+ */
+export declare function formatPhiMediaCompositeChecksum(digestHex: string, partCount: number, partSizeBytes: number): string;
+export declare function parsePhiMediaCompositeChecksum(value: string): {
+    digest: string;
+    partCount: number;
+    partSizeBytes: number;
+} | null;

package/dist/media.js

@@ -360,3 +360,62 @@ export function resolvePhiFontPreloadSubsetKeys(locale, coverage) {
             : PHI_FONT_SUBSET_PRELOAD_BY_LANGUAGE[language] ?? [];
     return [PhiFontSubsetKey.Latin, ...extra].filter((key) => coverage.subsets.includes(key));
 }
+/**
+ * How a body above one part is divided, as a rule rather than as a Provider's private arithmetic.
+ *
+ * It lives here because two parties have to agree on it and neither can be told by the other in time. The
+ * Provider needs the part size to sign one request per part; the Client needs it *before* the plan exists,
+ * because a digest can only be signed into a request if it is known when the request is signed -- so the
+ * Client has to hash the same divisions the Provider is about to address. A rule both compute from the
+ * byte size is the only arrangement where that holds without an extra round trip.
+ *
+ * **Frozen once objects exist under it.** A `sha256-composite` value is a digest of part digests, so it
+ * answers "the same bytes divided the same way". Change the division and the same file yields a different
+ * value, which splits duplicate detection into cohorts that can never match across the change. The value
+ * carries the part size for exactly this reason: a changed rule produces non-matches, never false matches.
+ * Changing it is therefore a decision about the whole corpus, not a tuning knob.
+ *
+ * `PHIS_MEDIA_UPLOAD_MAX_PART_COUNT` is well under S3's ten thousand on purpose. Every part is signed up
+ * front, so the count is also the size of the plan a Client receives and Core holds in memory.
+ */
+export const PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES = 16 * 1024 * 1024;
+export const PHIS_MEDIA_UPLOAD_MAX_PART_COUNT = 1000;
+/**
+ * The part size for one body, and the same answer wherever it is asked.
+ *
+ * Sixteen mebibytes until that would need more parts than are allowed, and from there the smallest whole
+ * mebibyte that fits the body into the allowance. Whole mebibytes keep the number short where it is
+ * recorded and keep the arithmetic exact in a browser, where sizes are doubles.
+ */
+export function resolvePhiMediaUploadPartSizeBytes(sizeBytes) {
+    const mebibyte = 1024 * 1024;
+    if (sizeBytes <= PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES * PHIS_MEDIA_UPLOAD_MAX_PART_COUNT) {
+        return PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES;
+    }
+    return Math.ceil(Math.ceil(sizeBytes / PHIS_MEDIA_UPLOAD_MAX_PART_COUNT) / mebibyte) * mebibyte;
+}
+/** How many parts one body is divided into under `resolvePhiMediaUploadPartSizeBytes`. */
+export function resolvePhiMediaUploadPartCount(sizeBytes) {
+    return Math.max(1, Math.ceil(sizeBytes / resolvePhiMediaUploadPartSizeBytes(sizeBytes)));
+}
+/**
+ * The recorded form of a `sha256-composite` digest: the digest, the part count, the part size.
+ *
+ * Duplicate detection compares these values as strings, so everything that decides whether two of them
+ * mean the same thing has to be inside the string. The digest alone would not: the same bytes divided
+ * differently hash differently, and a value that did not say how it was divided would look like a plain
+ * SHA-256 that simply failed to match. Naming the division makes a mismatch legible instead of puzzling.
+ */
+export function formatPhiMediaCompositeChecksum(digestHex, partCount, partSizeBytes) {
+    return `${digestHex.toLowerCase()}-${partCount}-${partSizeBytes}`;
+}
+export function parsePhiMediaCompositeChecksum(value) {
+    const match = /^([0-9a-f]{64})-(\d{1,5})-(\d{1,12})$/u.exec(value.trim().toLowerCase());
+    if (!match)
+        return null;
+    const partCount = Number(match[2]);
+    const partSizeBytes = Number(match[3]);
+    if (partCount < 1 || partSizeBytes < 1)
+        return null;
+    return { digest: match[1], partCount, partSizeBytes };
+}

package/dist/record.d.ts

@@ -0,0 +1,8 @@
+export declare function isPhiRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * The value a dotted path names inside a record: `"author.name"` reads `input.author.name`.
+ *
+ * Empty segments are skipped, so `""` names the input itself, and only records are walked -- an array
+ * or a primitive on the way ends the walk with `undefined` rather than being indexed into.
+ */
+export declare function readPhiDotPath(input: unknown, path: string): unknown;

package/dist/record.js

@@ -0,0 +1,24 @@
+/*
+ * Shared by the parsers of this package and not exported from it: each consumer keeps its own, and
+ * the one question they all answer is settled the same way -- an array is not a keyed record.
+ */
+export function isPhiRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * The value a dotted path names inside a record: `"author.name"` reads `input.author.name`.
+ *
+ * Empty segments are skipped, so `""` names the input itself, and only records are walked -- an array
+ * or a primitive on the way ends the walk with `undefined` rather than being indexed into.
+ */
+export function readPhiDotPath(input, path) {
+    let current = input;
+    for (const segment of path.split(".")) {
+        if (!segment)
+            continue;
+        if (!isPhiRecord(current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}