@phis/contracts 0.2.0 → 0.4.0

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,46 @@ 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;
+};
+/** 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.
+     *
+     * 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;
@@ -58,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 = {
@@ -72,16 +138,279 @@ 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, 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
+     * 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;
+    };
+    /**
+     * 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;
     /** 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", "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".
+ *
+ * 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[];
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * `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[];
+} | 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[];
+    /** 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>;
+    /**
+     * 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.
      *
@@ -108,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.
      *
@@ -127,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

@@ -7,3 +7,87 @@
  * 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", "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".
+ *
+ * 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", "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);
+}
+/**
+ * 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.
+ *
+ * `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;
+    }
+    return null;
+}