@phis/contracts 0.3.1 → 0.4.0

package/dist/capabilities.d.ts

@@ -12,7 +12,11 @@
  * at the point where it made the mistake.
  */
 import type { PhisAssetsCapabilityV1 } from "./assets.js";
+import type { PhisAddonEventId } from "./core.js";
 import type { PhisDataCapabilityV1 } from "./queries.js";
+import type { PhisResourceLinksCapabilityV1 } from "./resource-links.js";
+import type { PhisSupportCapabilityV1 } from "./support.js";
+import type { PhisThreadsCapabilityV1 } from "./threads.js";
 /**
  * The cumulative group levels, by name.
  *
@@ -94,6 +98,8 @@ export type PhisAddonCapabilities = {
     secrets?: PhisSecretsCapabilityV1;
     groups?: PhisGroupsCapabilityV1;
     threads?: PhisThreadsCapabilityV1;
+    resourceLinks?: PhisResourceLinksCapabilityV1;
+    support?: PhisSupportCapabilityV1;
     settings?: PhisSettingsCapabilityV1;
     roles?: PhisRolesCapabilityV1;
 };
@@ -128,17 +134,38 @@ export type PhisRolesCapabilityV1 = {
  * itself: a release artifact, a generated preview, an export waiting to be fetched.
  */
 export type PhisStorageCapabilityV1 = {
+    /**
+     * Both directions are streams, because two of the three things this store is for -- a release
+     * artifact and an export waiting to be fetched -- are the things that grow. A buffer would make the
+     * Site's largest allowed object the memory one call costs, on a path that only moves bytes.
+     *
+     * `byteSize` is declared rather than measured. The store's ceiling is booked before a byte is
+     * written, so that a write arriving at the same time as another cannot find room that the other
+     * already took, and nothing can be booked that has not been stated. Core counts while it writes and
+     * refuses a body that turns out not to be the size it claimed, so the declaration is a promise the
+     * Add-on is held to rather than one it is trusted on.
+     *
+     * An Add-on that already holds its bytes wraps them in a one-chunk `ReadableStream` and states
+     * `bytes.byteLength`.
+     */
     put(input: {
         key: string;
-        body: Uint8Array;
+        body: ReadableStream<Uint8Array>;
+        byteSize: number;
         contentType: string;
     }): Promise<{
         key: string;
         byteSize: number;
     }>;
-    /** Null rather than throwing for an object that is not there. */
+    /**
+     * Null rather than throwing for an object that is not there.
+     *
+     * The body arrives as it is read. `byteSize` comes with it so a caller that does need every byte can
+     * decide before it starts collecting them.
+     */
     get(key: string): Promise<{
-        body: Uint8Array;
+        body: ReadableStream<Uint8Array>;
+        byteSize: number;
         contentType: string;
     } | null>;
     head(key: string): Promise<{
@@ -323,93 +350,33 @@ export type PhisAddonJobContext = {
     signal: AbortSignal;
 };
 /**
- * The threads capability: `@phis/server/threads:v1`.
+ * One event Core hands an Add-on after the fact.
  *
- * Core's internal support threads, bounded by the acting user exactly as `groups:v1` is: an Add-on
- * reads the threads its actor is in and nothing else. A thread is visible to whoever created it, was
- * named a recipient of it, or stands in a team that was -- there is no listing that steps outside that,
- * because a Site's threads are its people talking and an Add-on is not a party to them.
+ * A handler runs with no actor -- nobody called it, something happened -- and reaches exactly what the
+ * link that caused the delivery reaches. It is the counterpart of a hook: a hook is the outside telling
+ * this Site something, an event is this Site telling an Add-on something, and both run as the Add-on
+ * rather than as a person.
  *
- * **Without an actor only `create` is offered.** A job and a hook run as the Add-on rather than as a
- * person, and a person is what thread visibility is made of: an Add-on with no actor is in no thread,
- * so there is nothing for it to list, read or answer. It may still open one -- naming its recipients as
- * it goes -- which is what an integration reporting an outside event needs. How such an integration
- * later appends to the thread it opened is deliberately left unanswered here: it wants a thread the
- * Add-on owns, and ownership of a thread is a thing to design once something real needs it rather than
- * to guess at now.
+ * Delivery is bounded by the same link. An Add-on is told about a thread it is synced with and about no
+ * other, because a Site-wide feed of everything anybody writes is the listing `threads:v1` refuses,
+ * arriving by push instead of by pull.
  */
-export type PhisThreadsCapabilityV1 = {
-    /** The threads the acting user is in, newest activity first. */
-    list(options?: {
-        page?: number;
-        pageSize?: number;
-        unreadOnly?: boolean;
-    }): Promise<PhisThreadSummary[]>;
-    /** One thread with a window of its messages, or null where the actor is not in it. */
-    get(threadId: number, options?: {
-        messageLimit?: number;
-        beforeMessageId?: number | null;
-    }): Promise<PhisThreadDetail | null>;
-    /**
-     * Opens a thread.
-     *
-     * The one call an Add-on may make with no actor behind it. Recipients are named as user ids, team
-     * ids, or both, and every one is checked against this Site before anything is written.
-     */
-    create(input: {
-        subject?: string | null;
-        message: string;
-        messageMarkdown?: string | null;
-        recipientUserIds?: number[];
-        recipientTeamIds?: number[];
-    }): Promise<PhisThreadDetail>;
-    /** Adds a message to a thread the acting user is in. */
-    reply(input: {
-        threadId: number;
-        message: string;
-        messageMarkdown?: string | null;
-    }): Promise<PhisThreadDetail | null>;
-    /** Brings more people into a thread the acting user is in. Adds only; it never removes. */
-    addRecipients(input: {
-        threadId: number;
-        recipientUserIds?: number[];
-        recipientTeamIds?: number[];
-    }): Promise<PhisThreadDetail | null>;
-    /**
-     * Takes a thread out of the active list, for everyone in it.
-     *
-     * One row carries the status, so this is the thread being closed rather than one reader hiding it.
-     */
-    archive(threadId: number): Promise<boolean>;
-    /** Marks the thread read for the acting user, up to its newest message or to one named. */
-    markRead(input: {
+export type PhisAddonEventContext = {
+    addonId: string;
+    event: PhisAddonEventId;
+    /** This delivery, stable across retries, so a handler can recognise one it already settled. */
+    deliveryId: string;
+    site: {
+        id: number;
+        key: string;
+    };
+    /** The thread the event happened in, and the message where the event is about one. */
+    subject: {
         threadId: number;
-        messageId?: number | null;
-    }): Promise<boolean>;
-};
-export type PhisThreadSummary = {
-    id: number;
-    subject: string | null;
-    status: number;
-    type: number;
-    createdAt: string;
-    updatedAt: string;
-    latestMessageAt: string | null;
-    unread: boolean;
-};
-export type PhisThreadMessage = {
-    id: number;
-    bodyText: string;
-    bodyMarkdown: string | null;
-    author: PhisUserProjection | null;
-    createdAt: string;
-};
-export type PhisThreadDetail = {
-    thread: PhisThreadSummary;
-    messages: PhisThreadMessage[];
-    /** Whether older messages remain beyond the window `messages` carries. */
-    hasMoreMessages: boolean;
-    recipientUserIds: number[];
-    recipientTeamIds: number[];
+        messageId: number | null;
+    };
+    capabilities: PhisAddonCapabilities;
+    signal: AbortSignal;
 };
+export type PhisAddonEventHandler = (context: PhisAddonEventContext) => Promise<void> | void;
 export type PhisAddonJobHandler = (context: PhisAddonJobContext) => Promise<void> | void;

package/dist/core.d.ts

@@ -47,6 +47,28 @@ export declare const PHIS_CORE_CAPABILITIES: {
     readonly roles: "@phis/server/roles:v1";
 };
 export type PhisCoreCapabilityId = (typeof PHIS_CORE_CAPABILITIES)[keyof typeof PHIS_CORE_CAPABILITIES];
+/**
+ * What Core tells an Add-on about after the fact.
+ *
+ * An integration that mirrors a conversation cannot wait to be asked: somebody writes a reply here and
+ * it has to appear over there, and no request the Add-on serves is involved. Polling would be the
+ * alternative, and polling for "did anybody write anything" is the Site-wide read every capability here
+ * is shaped to prevent.
+ *
+ * An event is delivered only to an Add-on linked to the thread it happened in, and a message this same
+ * Add-on imported is never announced back to it -- which is what stops a mirror from echoing.
+ *
+ * The list is short on purpose and grows when an Add-on needs an entry, the way the capability catalogue
+ * does. Every event a Site could emit, declared in advance, would be a contract to get wrong.
+ */
+export declare const PHIS_ADDON_EVENTS: {
+    readonly threadMessageCreated: "thread.message.created";
+    readonly threadMessageUpdated: "thread.message.updated";
+    readonly threadStatusChanged: "thread.status.changed";
+    /** The link itself is gone; what follows from that is the Add-on's own business. */
+    readonly threadLinkRemoved: "thread.link.removed";
+};
+export type PhisAddonEventId = (typeof PHIS_ADDON_EVENTS)[keyof typeof PHIS_ADDON_EVENTS];
 /**
  * The Core-owned service kinds an Add-on may implement.
  *
@@ -57,6 +79,15 @@ export type PhisCoreCapabilityId = (typeof PHIS_CORE_CAPABILITIES)[keyof typeof
 export declare const PHIS_SERVICE_KINDS: {
     readonly mediaStorage: "@phis/server/service/media-storage";
     readonly directory: "@phis/server/service/directory";
+    /**
+     * Turning text in one language into text in another.
+     *
+     * A kind rather than a capability for the same reason as the two above: Core owns the question and
+     * keeps asking it, and what an implementation talks to -- a vendor, a model on the machine, a
+     * catalogue it maintains itself -- is its own business. Several may be installed at once; the
+     * operator selects which one an installation uses.
+     */
+    readonly translation: "@phis/server/service/translation";
 };
 export type PhisServiceKind = (typeof PHIS_SERVICE_KINDS)[keyof typeof PHIS_SERVICE_KINDS];
 /**
@@ -69,6 +100,13 @@ export type PhisServiceKind = (typeof PHIS_SERVICE_KINDS)[keyof typeof PHIS_SERV
  *
  * The digest is `sha256("phi-server-service-kind:<kind>:v<interface version>")`. That recipe is
  * documented for whoever has to produce the next value; nothing needs to run it to read a manifest.
+ *
+ * **Before the v1 release every version here stays at 1, whatever changes shape.** There is no released
+ * Add-on to protect and nothing in the field built against an older interface, so raising a version buys
+ * no compatibility and costs the installation: the recorded manifest of every installed Add-on stops
+ * matching, `buildPhisCapabilitySnapshot` refuses the desired state, and every request that resolves a
+ * viewer answers 500 until each Add-on has been rebundled and upgraded. An interface that changes before
+ * v1 is simply the interface, and both sides are rebuilt from one tree.
  */
 export declare const PHIS_SERVICE_INTERFACE_VERSIONS: Readonly<Record<PhisServiceKind, number>>;
 export declare const PHIS_SERVICE_INTERFACE_DIGESTS: Readonly<Record<PhisServiceKind, string>>;

package/dist/core.js

@@ -46,6 +46,27 @@ export const PHIS_CORE_CAPABILITIES = {
     /** Whether the acting user holds one of this Add-on's own declared roles. */
     roles: "@phis/server/roles:v1",
 };
+/**
+ * What Core tells an Add-on about after the fact.
+ *
+ * An integration that mirrors a conversation cannot wait to be asked: somebody writes a reply here and
+ * it has to appear over there, and no request the Add-on serves is involved. Polling would be the
+ * alternative, and polling for "did anybody write anything" is the Site-wide read every capability here
+ * is shaped to prevent.
+ *
+ * An event is delivered only to an Add-on linked to the thread it happened in, and a message this same
+ * Add-on imported is never announced back to it -- which is what stops a mirror from echoing.
+ *
+ * The list is short on purpose and grows when an Add-on needs an entry, the way the capability catalogue
+ * does. Every event a Site could emit, declared in advance, would be a contract to get wrong.
+ */
+export const PHIS_ADDON_EVENTS = {
+    threadMessageCreated: "thread.message.created",
+    threadMessageUpdated: "thread.message.updated",
+    threadStatusChanged: "thread.status.changed",
+    /** The link itself is gone; what follows from that is the Add-on's own business. */
+    threadLinkRemoved: "thread.link.removed",
+};
 /**
  * The Core-owned service kinds an Add-on may implement.
  *
@@ -56,6 +77,15 @@ export const PHIS_CORE_CAPABILITIES = {
 export const PHIS_SERVICE_KINDS = {
     mediaStorage: "@phis/server/service/media-storage",
     directory: "@phis/server/service/directory",
+    /**
+     * Turning text in one language into text in another.
+     *
+     * A kind rather than a capability for the same reason as the two above: Core owns the question and
+     * keeps asking it, and what an implementation talks to -- a vendor, a model on the machine, a
+     * catalogue it maintains itself -- is its own business. Several may be installed at once; the
+     * operator selects which one an installation uses.
+     */
+    translation: "@phis/server/service/translation",
 };
 /**
  * The digest of the interface each service kind currently has.
@@ -67,12 +97,21 @@ export const PHIS_SERVICE_KINDS = {
  *
  * The digest is `sha256("phi-server-service-kind:<kind>:v<interface version>")`. That recipe is
  * documented for whoever has to produce the next value; nothing needs to run it to read a manifest.
+ *
+ * **Before the v1 release every version here stays at 1, whatever changes shape.** There is no released
+ * Add-on to protect and nothing in the field built against an older interface, so raising a version buys
+ * no compatibility and costs the installation: the recorded manifest of every installed Add-on stops
+ * matching, `buildPhisCapabilitySnapshot` refuses the desired state, and every request that resolves a
+ * viewer answers 500 until each Add-on has been rebundled and upgraded. An interface that changes before
+ * v1 is simply the interface, and both sides are rebuilt from one tree.
  */
 export const PHIS_SERVICE_INTERFACE_VERSIONS = {
     [PHIS_SERVICE_KINDS.mediaStorage]: 1,
     [PHIS_SERVICE_KINDS.directory]: 1,
+    [PHIS_SERVICE_KINDS.translation]: 1,
 };
 export const PHIS_SERVICE_INTERFACE_DIGESTS = {
     [PHIS_SERVICE_KINDS.mediaStorage]: "45a871522511f7d77841ca8dd0113b423b3cfd4cb921f143cd1d3d116cab6952",
     [PHIS_SERVICE_KINDS.directory]: "2cac7397c7beb1b8e71fc67f5cae3be89182dddf096895570a15deafa1adbfc9",
+    [PHIS_SERVICE_KINDS.translation]: "9bae2e7b92ded5cdde9321939a3bb8cd589f6e1ef8bca7bc5f65608313b3207d",
 };

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.
      *