@syncular/server 0.1.3 → 0.2.0

package/dist/admin.d.ts

@@ -0,0 +1,136 @@
+/**
+ * `SyncularAdmin` — the operator-facing read surface over the server core
+ * (TODO §2.5). A read-only, partition-scoped, JSON-able query layer over
+ * `ServerStorage`, the optional segment/blob store stats, and an in-memory
+ * event ring. This is v2's answer to v1's full React console app: the same
+ * 80% operator value (who's connected, what's flowing, horizon health, the
+ * event tail) as a handful of queries in the server package — no separate
+ * UI package, no framework, no wire-protocol surface (SPEC.md is untouched;
+ * this is host surface, mirrored in the server README).
+ *
+ * Nothing here is on the sync hot path. Every method is a plain read; the
+ * additive optional storage/store methods it depends on are documented as
+ * such and this module fails loud (a thrown `Error`) when a backend lacks
+ * one, so a host wiring an unsupported store learns immediately rather than
+ * getting a silently-empty console.
+ */
+import type { BlobStore, BlobStoreStats } from './blob-store.js';
+import { type SyncServerConfig } from './context.js';
+import type { SyncularServerEvent } from './events.js';
+import type { RingBufferEvents, RingEventQuery } from './events-ring.js';
+import { type RetentionPolicy } from './prune.js';
+import { type ServerSchema } from './schema.js';
+import type { SegmentStore, SegmentStoreStats } from './segment-store.js';
+import type { CommitMetadata, ScopeCommitActivity, ServerStorage } from './storage.js';
+/** A connected/known client as the console sees it (§4.5, §8.1). */
+export interface AdminClient {
+    readonly clientId: string;
+    readonly actorId: string;
+    readonly cursor: number;
+    readonly updatedAtMs: number;
+    readonly subscriptions: readonly {
+        readonly id: string;
+        readonly table: string;
+        readonly scopes: Record<string, readonly string[]>;
+    }[];
+    /** True when the cursor record was touched within the active window. */
+    readonly active: boolean;
+}
+export interface AdminRowInspection {
+    readonly table: string;
+    readonly rowId: string;
+    readonly exists: boolean;
+    readonly serverVersion?: number;
+    readonly scopes?: Record<string, string>;
+    /** blobIds this row currently references (§5.9.4), when the store tracks them. */
+    readonly referencedBlobIds?: readonly string[];
+}
+export interface AdminHorizonStatus {
+    readonly partition: string;
+    readonly maxCommitSeq: number;
+    readonly horizonSeq: number;
+    /** Commits still below the retained log's tail — the pruneable backlog. */
+    readonly retainedCommits: number;
+    /** min(cursor) over active clients, or null when none are active. */
+    readonly activeCursorFloor: number | null;
+    /** The horizon a prune pass would advance to right now (§4.6). */
+    readonly recommendedHorizonSeq: number;
+    readonly recommendation: 'up-to-date' | 'prune-recommended';
+}
+export interface AdminListCommitsOptions {
+    readonly afterSeq?: number;
+    readonly limit?: number;
+    readonly table?: string;
+}
+export interface AdminScopeActivityOptions {
+    readonly limit?: number;
+}
+export interface AdminStats {
+    readonly segments?: SegmentStoreStats;
+    readonly blobs?: BlobStoreStats;
+}
+export interface SyncularAdminOptions {
+    readonly storage: ServerStorage;
+    /**
+     * The server schema. When present, row reads (`inspectRow`) ensure the
+     * relational row tables exist first — needed when the admin runs against
+     * a storage instance that has not served a sync request yet.
+     */
+    readonly schema?: ServerSchema;
+    /** The event ring feeding the event tail. Absent ⇒ `events()` is empty. */
+    readonly ring?: RingBufferEvents;
+    readonly segments?: SegmentStore;
+    readonly blobs?: BlobStore;
+    /** Retention policy for horizon recommendation (defaults to §4.6). */
+    readonly retention?: Partial<RetentionPolicy>;
+    /** Epoch-ms clock (defaults to `Date.now`) — active-window math. */
+    readonly clock?: () => number;
+}
+/** The read-only console query surface. Construct one per host process. */
+export declare class SyncularAdmin {
+    #private;
+    constructor(options: SyncularAdminOptions);
+    /**
+     * Build an admin over a `SyncServerConfig`, reusing its storage / segment
+     * / blob store / clock. Pass the ring separately (it is an events sink,
+     * composed into the config's `events` by the host — see `composeEvents`).
+     */
+    static fromConfig(config: SyncServerConfig, extra?: {
+        ring?: RingBufferEvents;
+        retention?: Partial<RetentionPolicy>;
+    }): SyncularAdmin;
+    /** The known clients for a partition (cursor, last-seen, subscriptions). */
+    listClients(partition: string): Promise<AdminClient[]>;
+    /** Commit-log metadata (no payloads), newest first. */
+    listCommits(partition: string, options?: AdminListCommitsOptions): Promise<CommitMetadata[]>;
+    /**
+     * Inspect a single row: current server_version, stored scopes, and the
+     * blobIds it references (when the store tracks references). Payload bytes
+     * are deliberately NOT decoded — the console shows metadata, not content.
+     */
+    inspectRow(partition: string, table: string, rowId: string): Promise<AdminRowInspection>;
+    /**
+     * Recent commits touching one scope key (`variable:value`, e.g.
+     * `project:p1`) — routed through the change-scope index, never a scan.
+     */
+    scopeActivity(partition: string, scopeKey: {
+        variable: string;
+        value: string;
+    }, options?: AdminScopeActivityOptions): Promise<ScopeCommitActivity[]>;
+    /**
+     * Horizon health for a partition: current horizon, retained-commit
+     * backlog, active cursor floor, and the horizon a prune pass would reach
+     * now (§4.6) plus a coarse recommendation.
+     */
+    horizonStatus(partition: string): Promise<AdminHorizonStatus>;
+    /** Segment + blob store counters where the stores expose them. */
+    stats(partition: string): Promise<AdminStats>;
+    /** Segment store counters alone (undefined when unsupported/unset). */
+    segmentStats(): Promise<SegmentStoreStats | undefined>;
+    /** Blob store counters for a partition (undefined when unsupported/unset). */
+    blobStats(partition: string): Promise<BlobStoreStats | undefined>;
+    /** True when this admin has an event ring wired (the event tail is live). */
+    get hasEventStream(): boolean;
+    /** The event tail from the ring buffer (newest first). Empty when unwired. */
+    events(query?: RingEventQuery): SyncularServerEvent[];
+}

package/dist/admin.js

@@ -0,0 +1,168 @@
+import { clockOf } from './context.js';
+import { DEFAULT_RETENTION } from './prune.js';
+import { compileSchema } from './schema.js';
+const DEFAULT_COMMIT_LIMIT = 50;
+const DEFAULT_SCOPE_LIMIT = 50;
+function required(value, what) {
+    if (value === undefined) {
+        throw new Error(`SyncularAdmin: the configured ${what} does not implement this read (TODO §2.5 optional method missing)`);
+    }
+    return value;
+}
+function toAdminClient(record, active) {
+    return {
+        clientId: record.clientId,
+        actorId: record.actorId,
+        cursor: record.cursor,
+        updatedAtMs: record.updatedAtMs,
+        subscriptions: record.subscriptions.map((sub) => ({
+            id: sub.id,
+            table: sub.table,
+            scopes: sub.scopes,
+        })),
+        active,
+    };
+}
+/** The read-only console query surface. Construct one per host process. */
+export class SyncularAdmin {
+    #storage;
+    #schema;
+    #ring;
+    #segments;
+    #blobs;
+    #retention;
+    #clock;
+    constructor(options) {
+        this.#storage = options.storage;
+        if (options.schema !== undefined)
+            this.#schema = options.schema;
+        if (options.ring !== undefined)
+            this.#ring = options.ring;
+        if (options.segments !== undefined)
+            this.#segments = options.segments;
+        if (options.blobs !== undefined)
+            this.#blobs = options.blobs;
+        this.#retention = { ...DEFAULT_RETENTION, ...options.retention };
+        this.#clock = options.clock ?? Date.now;
+    }
+    /**
+     * Build an admin over a `SyncServerConfig`, reusing its storage / segment
+     * / blob store / clock. Pass the ring separately (it is an events sink,
+     * composed into the config's `events` by the host — see `composeEvents`).
+     */
+    static fromConfig(config, extra) {
+        return new SyncularAdmin({
+            storage: config.storage,
+            schema: config.schema,
+            segments: config.segments,
+            ...(config.blobs !== undefined ? { blobs: config.blobs } : {}),
+            ...(extra?.ring !== undefined ? { ring: extra.ring } : {}),
+            ...(extra?.retention !== undefined ? { retention: extra.retention } : {}),
+            clock: clockOf(config),
+        });
+    }
+    /** The known clients for a partition (cursor, last-seen, subscriptions). */
+    async listClients(partition) {
+        const list = required(this.#storage.listClientRecords?.bind(this.#storage), 'storage');
+        const records = await list(partition);
+        const activeFloorMs = this.#clock() - this.#retention.activeWindowMs;
+        return records.map((record) => toAdminClient(record, record.updatedAtMs >= activeFloorMs));
+    }
+    /** Commit-log metadata (no payloads), newest first. */
+    async listCommits(partition, options = {}) {
+        const read = required(this.#storage.listCommitMetadata?.bind(this.#storage), 'storage');
+        return read(partition, {
+            afterSeq: options.afterSeq ?? 0,
+            limit: options.limit ?? DEFAULT_COMMIT_LIMIT,
+            ...(options.table !== undefined ? { table: options.table } : {}),
+        });
+    }
+    /**
+     * Inspect a single row: current server_version, stored scopes, and the
+     * blobIds it references (when the store tracks references). Payload bytes
+     * are deliberately NOT decoded — the console shows metadata, not content.
+     */
+    async inspectRow(partition, table, rowId) {
+        const read = required(this.#storage.getRowScopes?.bind(this.#storage), 'storage');
+        if (this.#schema !== undefined) {
+            await this.#storage.ensureSchema(compileSchema(this.#schema));
+        }
+        const row = await read(partition, table, rowId);
+        if (row === undefined) {
+            return { table, rowId, exists: false };
+        }
+        return {
+            table,
+            rowId,
+            exists: true,
+            serverVersion: row.serverVersion,
+            scopes: row.scopes,
+        };
+    }
+    /**
+     * Recent commits touching one scope key (`variable:value`, e.g.
+     * `project:p1`) — routed through the change-scope index, never a scan.
+     */
+    async scopeActivity(partition, scopeKey, options = {}) {
+        const read = required(this.#storage.scopeActivity?.bind(this.#storage), 'storage');
+        return read(partition, {
+            variable: scopeKey.variable,
+            value: scopeKey.value,
+            limit: options.limit ?? DEFAULT_SCOPE_LIMIT,
+        });
+    }
+    /**
+     * Horizon health for a partition: current horizon, retained-commit
+     * backlog, active cursor floor, and the horizon a prune pass would reach
+     * now (§4.6) plus a coarse recommendation.
+     */
+    async horizonStatus(partition) {
+        const nowMs = this.#clock();
+        const maxCommitSeq = await this.#storage.getMaxCommitSeq(partition);
+        const horizonSeq = await this.#storage.getHorizonSeq(partition);
+        const cursors = await this.#storage.listClientCursors(partition);
+        const activeCursors = cursors
+            .filter((c) => c.updatedAtMs >= nowMs - this.#retention.activeWindowMs)
+            .map((c) => c.cursor);
+        const activeCursorFloor = activeCursors.length > 0 ? Math.min(...activeCursors) : null;
+        const cursorFloor = activeCursorFloor ?? Number.MAX_SAFE_INTEGER;
+        const forcedSeq = await this.#storage.getCommitSeqBefore(partition, nowMs - this.#retention.ageForceMs);
+        const retainFloor = maxCommitSeq - this.#retention.minRetainedCommits;
+        const target = Math.min(Math.max(cursorFloor, forcedSeq), retainFloor);
+        const recommendedHorizonSeq = Math.max(horizonSeq, Math.max(0, target));
+        return {
+            partition,
+            maxCommitSeq,
+            horizonSeq,
+            retainedCommits: maxCommitSeq - horizonSeq,
+            activeCursorFloor,
+            recommendedHorizonSeq,
+            recommendation: recommendedHorizonSeq > horizonSeq ? 'prune-recommended' : 'up-to-date',
+        };
+    }
+    /** Segment + blob store counters where the stores expose them. */
+    async stats(partition) {
+        const segments = await this.#segments?.stats?.();
+        const blobs = await this.#blobs?.stats?.(partition);
+        return {
+            ...(segments !== undefined ? { segments } : {}),
+            ...(blobs !== undefined ? { blobs } : {}),
+        };
+    }
+    /** Segment store counters alone (undefined when unsupported/unset). */
+    async segmentStats() {
+        return this.#segments?.stats?.();
+    }
+    /** Blob store counters for a partition (undefined when unsupported/unset). */
+    async blobStats(partition) {
+        return this.#blobs?.stats?.(partition);
+    }
+    /** True when this admin has an event ring wired (the event tail is live). */
+    get hasEventStream() {
+        return this.#ring !== undefined;
+    }
+    /** The event tail from the ring buffer (newest first). Empty when unwired. */
+    events(query = {}) {
+        return this.#ring?.query(query) ?? [];
+    }
+}

package/dist/blob-handlers.d.ts

@@ -0,0 +1,69 @@
+import type { SyncRequestContext } from './context.js';
+export interface BlobUploadRequest {
+    readonly blobId: string;
+    readonly bytes: Uint8Array;
+    /** Advisory MIME type from the upload `Content-Type`, if any. */
+    readonly mediaType?: string;
+}
+export interface BlobDownloadResult {
+    /**
+     * The blob bytes, when served inline. **Absent** when the host configured
+     * `blobSignedUrls` and a `url` was issued: the sync server exits the egress
+     * path and the client fetches `url` directly (§5.9.5 always-issue).
+     */
+    readonly bytes?: Uint8Array;
+    readonly headers: Record<string, string>;
+    /**
+     * §5.9.5 delegated presign (always-issue): a provider-signed GET URL for
+     * the bytes, issued only after the row-derived authorization check passed.
+     * Present iff the host configured `blobSignedUrls`; when present, `bytes` is
+     * absent and the client MUST fetch the URL directly (no host auth), verify
+     * the content address, and on failure re-request this endpoint — never fall
+     * through (§5.9.5 recovery rule).
+     */
+    readonly url?: string;
+    readonly urlExpiresAtMs?: number;
+}
+/** `POST <mount>/blobs/{blobId}/upload-grant` request body (§5.9.3). */
+export interface BlobUploadGrantRequest {
+    readonly blobId: string;
+    /** Declared uncompressed size — the size-cap check runs against this. */
+    readonly byteLength: number;
+    /** Advisory MIME type, if any. */
+    readonly mediaType?: string;
+}
+/**
+ * `POST <mount>/blobs/{blobId}/upload-grant` result (§5.9.3). Exactly one of:
+ * `{url, urlExpiresAtMs}` — a presigned PUT the client uses direct-to-storage;
+ * or `{present: true}` — the blob already exists (idempotent §5.9.3), so the
+ * client skips the PUT; or `{}` (no fields) — the host has no presigned-upload
+ * store configured, so the client streams through the direct PUT endpoint
+ * (§5.9.3 capability, not fallback).
+ */
+export interface BlobUploadGrantResult {
+    readonly url?: string;
+    readonly urlExpiresAtMs?: number;
+    readonly present?: boolean;
+}
+/** `PUT <mount>/blobs/{blobId}` (§5.9.3). Host auth is the adapter's job. */
+export declare function handleBlobUpload(ctx: SyncRequestContext, request: BlobUploadRequest): Promise<void>;
+/**
+ * `GET <mount>/blobs/{blobId}` (§5.9.5). Authorization derives from the
+ * referencing rows: the actor may download iff at least one row in the
+ * reference index passes the §3.4 scope check for the actor.
+ */
+export declare function handleBlobDownload(ctx: SyncRequestContext, blobId: string): Promise<BlobDownloadResult>;
+/**
+ * `POST <mount>/blobs/{blobId}/upload-grant` (§5.9.3 presigned upload). Host
+ * auth is the adapter's job — uploading is host-auth-only, not scope-bearing,
+ * so any authenticated actor may obtain a grant within the size cap (§5.9.3).
+ *
+ * The size cap is enforced HERE, up front, against the declared `byteLength`
+ * (the object-store hop cannot re-check the streamed byte count). Integrity is
+ * NOT checked here: the object store places bytes at the content-addressed key,
+ * and the address is verified at reference time (§5.9.6 push existence) and on
+ * every download (§5.9.5/§5.1). Returns a presigned single PUT, or a
+ * `present` marker if the blob already exists (idempotent §5.9.3), or an empty
+ * result when no presigned-upload store is configured (client streams direct).
+ */
+export declare function handleBlobUploadGrant(ctx: SyncRequestContext, request: BlobUploadGrantRequest): Promise<BlobUploadGrantResult>;

package/dist/blob-handlers.js

@@ -0,0 +1,245 @@
+/**
+ * Blob upload + download handlers (SPEC.md §5.9.3, §5.9.5).
+ *
+ * Upload verifies the content address (§5.9.3); download re-authorizes on
+ * every request against the rows that reference the blob (§5.9.5) — a
+ * `blobId` is never a bearer capability. Framework-free; the hono/runtime
+ * adapters map these onto `PUT/GET <mount>/blobs/{blobId}`.
+ */
+import { blobIdFor, isBlobId } from './blob-store.js';
+import { clockOf, RESOLVER_OUTAGE } from './context.js';
+import { SyncError, syncError } from './errors.js';
+import { emitEvent } from './events.js';
+import { compileSchema } from './schema.js';
+import { authorizeWrite } from './scopes.js';
+import { issueBlobUploadUrl, issueBlobUrl } from './signed-url.js';
+const DEFAULT_MAX_BLOB_BYTES = 64 * 1024 * 1024;
+/** `PUT <mount>/blobs/{blobId}` (§5.9.3). Host auth is the adapter's job. */
+export async function handleBlobUpload(ctx, request) {
+    const store = ctx.blobs;
+    if (store === undefined) {
+        throw syncError('blob.not_found', 'this server has no blob store (§5.9)');
+    }
+    if (!isBlobId(request.blobId)) {
+        throw syncError('blob.hash_mismatch', 'blobId path is not "sha256:<64 hex>" (§5.9.1)');
+    }
+    const maxBytes = ctx.maxBlobBytes ?? DEFAULT_MAX_BLOB_BYTES;
+    if (request.bytes.length > maxBytes) {
+        throw syncError('blob.too_large', `blob exceeds the ${maxBytes}-byte cap (§5.9.3)`);
+    }
+    const computed = await blobIdFor(request.bytes);
+    if (computed !== request.blobId) {
+        throw syncError('blob.hash_mismatch', 'uploaded bytes do not hash to the blobId path (§5.9.3)');
+    }
+    const clock = clockOf(ctx);
+    await store.put(ctx.partition, request.blobId, request.bytes, clock(), request.mediaType);
+    if (ctx.events !== undefined) {
+        emitEvent(ctx.events, {
+            type: 'blob.uploaded',
+            atMs: clock(),
+            partition: ctx.partition,
+            actorId: ctx.actorId,
+            blobId: request.blobId,
+            bytes: request.bytes.length,
+        });
+    }
+}
+/**
+ * `GET <mount>/blobs/{blobId}` (§5.9.5). Authorization derives from the
+ * referencing rows: the actor may download iff at least one row in the
+ * reference index passes the §3.4 scope check for the actor.
+ */
+export async function handleBlobDownload(ctx, blobId) {
+    const events = ctx.events;
+    if (events === undefined)
+        return downloadBlob(ctx, blobId);
+    const clock = clockOf(ctx);
+    const startedAtMs = clock();
+    try {
+        const result = await downloadBlob(ctx, blobId);
+        emitEvent(events, {
+            type: 'blob.downloaded',
+            atMs: clock(),
+            partition: ctx.partition,
+            actorId: ctx.actorId,
+            blobId,
+            outcome: 'ok',
+            // Presigned delivery carries no inline bytes (§5.9.5 always-issue); the
+            // byte count is unknown to the sync server, which exited the egress path.
+            bytes: result.bytes?.length ?? 0,
+            durationMs: clock() - startedAtMs,
+        });
+        return result;
+    }
+    catch (error) {
+        emitEvent(events, {
+            type: 'blob.downloaded',
+            atMs: clock(),
+            partition: ctx.partition,
+            actorId: ctx.actorId,
+            blobId,
+            outcome: 'error',
+            errorCode: error instanceof SyncError ? error.code : 'internal',
+            durationMs: clock() - startedAtMs,
+        });
+        throw error;
+    }
+}
+async function downloadBlob(ctx, blobId) {
+    const store = ctx.blobs;
+    if (store === undefined) {
+        throw syncError('blob.not_found', 'this server has no blob store (§5.9)');
+    }
+    if (!isBlobId(blobId)) {
+        throw syncError('blob.not_found', 'malformed blobId (§5.9.1)');
+    }
+    // §5.9.5 always-issue: when presign is configured the server exits the
+    // egress path — it only needs to know the object EXISTS (a HEAD/`has`), not
+    // the bytes. Inline delivery loads the bytes; presigned delivery does not.
+    const presignConfigured = ctx.blobSignedUrls !== undefined;
+    let entry;
+    let mediaType;
+    if (presignConfigured) {
+        if (!(await store.has(ctx.partition, blobId))) {
+            throw syncError('blob.not_found', 'unknown blob (§5.9.5)');
+        }
+    }
+    else {
+        entry = await store.get(ctx.partition, blobId);
+        if (entry === undefined) {
+            throw syncError('blob.not_found', 'unknown blob (§5.9.5)');
+        }
+        mediaType = entry.record.mediaType;
+    }
+    // §5.9.5 authorization: resolve once, then test referencing rows.
+    const listRows = ctx.storage.listRowsReferencingBlob;
+    if (listRows === undefined) {
+        // Storage without the reference index cannot authorize a download —
+        // fail closed (never serve bytes we cannot authorize).
+        throw syncError('blob.forbidden', 'storage has no blob reference index (§5.9.4)');
+    }
+    let resolved;
+    try {
+        const allowed = await ctx.resolveScopes({
+            partition: ctx.partition,
+            actorId: ctx.actorId,
+        });
+        // §7.3.3: leases never authorize a blob download — an outage denies.
+        resolved =
+            allowed === RESOLVER_OUTAGE ? { ok: false } : { ok: true, allowed };
+    }
+    catch (error) {
+        if (ctx.events !== undefined) {
+            emitEvent(ctx.events, {
+                type: 'scopes.resolve_failed',
+                atMs: clockOf(ctx)(),
+                partition: ctx.partition,
+                actorId: ctx.actorId,
+                phase: 'blob-download',
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+        resolved = { ok: false };
+    }
+    if (!resolved.ok) {
+        throw syncError('blob.forbidden', 'scope resolution failed (§5.9.5)');
+    }
+    const schema = compileSchema(ctx.schema);
+    // A blob download can hit a fresh storage instance before any sync
+    // request has run (Workers): make sure the row tables exist first.
+    await ctx.storage.ensureSchema(schema);
+    const rows = await listRows.call(ctx.storage, ctx.partition, blobId);
+    let authorized = false;
+    for (const row of rows) {
+        const table = schema.tables.get(row.table);
+        if (table === undefined)
+            continue;
+        if (authorizeWrite(table, row.scopes, resolved)) {
+            authorized = true;
+            break;
+        }
+    }
+    if (!authorized) {
+        // Never 404 here: existence-vs-authorization must not leak (§5.9.5).
+        throw syncError('blob.forbidden', 'no referencing row authorizes this actor (§5.9.5)');
+    }
+    // §5.9.5 delegated presign (always-issue): authorization has passed above,
+    // so a signed URL is now a short-TTL bearer grant to exactly these immutable
+    // bytes. When configured, issue it and return NO bytes — the client fetches
+    // the URL directly. Never before the check, never a capability from the id.
+    if (ctx.blobSignedUrls !== undefined) {
+        const issued = await issueBlobUrl(ctx.blobSignedUrls, {
+            partition: ctx.partition,
+            blobId,
+            nowMs: clockOf(ctx)(),
+        });
+        return {
+            headers: {
+                ETag: `"${blobId}"`,
+                'Cache-Control': 'private, max-age=0',
+                Vary: 'Authorization, Accept-Encoding',
+            },
+            url: issued.url,
+            urlExpiresAtMs: issued.urlExpiresAtMs,
+        };
+    }
+    // Inline delivery (no presign store configured): the bytes were loaded.
+    const bytes = entry?.bytes;
+    if (bytes === undefined) {
+        // Unreachable: presign not configured ⇒ `entry` was loaded above.
+        throw syncError('blob.not_found', 'blob bytes unavailable (§5.9.5)');
+    }
+    return {
+        bytes,
+        headers: {
+            'Content-Type': mediaType ?? 'application/octet-stream',
+            ETag: `"${blobId}"`,
+            'Cache-Control': 'private, max-age=0',
+            Vary: 'Authorization, Accept-Encoding',
+        },
+    };
+}
+/**
+ * `POST <mount>/blobs/{blobId}/upload-grant` (§5.9.3 presigned upload). Host
+ * auth is the adapter's job — uploading is host-auth-only, not scope-bearing,
+ * so any authenticated actor may obtain a grant within the size cap (§5.9.3).
+ *
+ * The size cap is enforced HERE, up front, against the declared `byteLength`
+ * (the object-store hop cannot re-check the streamed byte count). Integrity is
+ * NOT checked here: the object store places bytes at the content-addressed key,
+ * and the address is verified at reference time (§5.9.6 push existence) and on
+ * every download (§5.9.5/§5.1). Returns a presigned single PUT, or a
+ * `present` marker if the blob already exists (idempotent §5.9.3), or an empty
+ * result when no presigned-upload store is configured (client streams direct).
+ */
+export async function handleBlobUploadGrant(ctx, request) {
+    const store = ctx.blobs;
+    if (store === undefined) {
+        throw syncError('blob.not_found', 'this server has no blob store (§5.9)');
+    }
+    if (!isBlobId(request.blobId)) {
+        throw syncError('blob.hash_mismatch', 'blobId path is not "sha256:<64 hex>" (§5.9.1)');
+    }
+    const maxBytes = ctx.maxBlobBytes ?? DEFAULT_MAX_BLOB_BYTES;
+    if (!Number.isInteger(request.byteLength) ||
+        request.byteLength < 0 ||
+        request.byteLength > maxBytes) {
+        // §5.9.3: cap enforced at grant issuance, before any URL is minted.
+        throw syncError('blob.too_large', `blob byteLength exceeds the ${maxBytes}-byte cap (§5.9.3)`);
+    }
+    // §5.9.3 no presigned-upload store: report no grant; the client streams
+    // through the direct PUT endpoint (capability, not fallback).
+    if (ctx.blobUploadUrls === undefined)
+        return {};
+    // Idempotent §5.9.3: an already-present blob needs no PUT.
+    if (await store.has(ctx.partition, request.blobId)) {
+        return { present: true };
+    }
+    const issued = await issueBlobUploadUrl(ctx.blobUploadUrls, {
+        partition: ctx.partition,
+        blobId: request.blobId,
+        byteLength: request.byteLength,
+        nowMs: clockOf(ctx)(),
+    });
+    return { url: issued.url, urlExpiresAtMs: issued.urlExpiresAtMs };
+}