@hozon/blob 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Le Cam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,82 @@
-# Temporary Holding Version
+# @hozon/blob
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+Content-addressed blob service: verified writes over a `BlobBackend` with metadata in `@hozon/store-blob`.
+Portable: no Node.js APIs.
+
+```sh
+pnpm add @hozon/blob @hozon/blob-backend @hozon/store-blob @hozon/db
+```
+
+```ts
+import { MemoryBlobBackend } from '@hozon/blob-backend'
+import { createBlobService } from '@hozon/blob'
+import { blobStoreDefinition } from '@hozon/store-blob'
+
+// Registering the store definition is the caller's job.
+db.register(blobStoreDefinition)
+const blobs = createBlobService({ db, backend: new MemoryBlobBackend() })
+
+const { entry, created } = await blobs.write({ stream, contentType: 'image/png' })
+```
+
+Options: `codec` (default `blake3Codec`), `chunkSize` (default 1 MiB), `lock` (default `createMemoryBlobLock()`), and `limits` (`maxBlobSize` 1 GiB, `maxChunkSize` 16 MiB, `minChunkSize` 1 KiB).
+`createBlobService` throws `Invalid chunkSize` when `chunkSize` is outside the chunk limits, and `Invalid limits` for invalid limits.
+
+## Write
+
+`write(stream, { contentType?, encrypted?, keyID?, expectedID?, maxSize?, signal? })` returns `{ entry, created }`.
+
+1. `expectedID` is canonicalized and decoded before the body is read. A content type embedded in the ID fills an omitted `contentType`; a different one throws `ContentTypeMismatchError`. A decoded length above the limit throws `BlobTooLargeError`.
+2. The body streams into a fresh staging area while hashing. Crossing `min(maxSize, limits.maxBlobSize)` throws `BlobTooLargeError`. A stream error aborts staging and rethrows it.
+3. A computed ID different from `expectedID` throws `BlobIDMismatchError`.
+4. Under the blob lock: an already-local blob keeps its metadata (a null `contentType` is filled from this write) and returns `created: false`. Otherwise bytes are committed, then the entry and manifest are recorded, replacing any `remote-only` or `partial` state and discarding that transfer's staging area.
+
+Bytes are committed before the row, so a failure leaves only orphan bytes, never a row without bytes.
+A `contentType` that is not a string of at most 255 characters throws `Error('Invalid contentType')` before the body is read.
+Aborting `signal` stops reading, discards staging, and throws `BlobWriteAbortedError`; the signal is checked again before commit.
+
+`writeWith({ stream, ...options, fn })` records the entry and calls `fn(tx, entry)` in one store transaction, returning `{ entry, created, result }`.
+It takes the blob lock before the transaction; the caller must not already be inside a store transaction (single-connection SQLite would deadlock).
+If `fn` throws, the transaction rolls back and the committed bytes remain as orphans.
+While `fn` runs the service holds the blob lock and, on SQLite, the single connection. `fn` must use only `tx`; it must not call blob service methods or use the outer `db`, which would deadlock.
+
+## Read and manage
+
+`get(id)`, `list({ limit, cursor })`, `has(id)` (true only for `local` entries), `getChunkDigests(id)` (returns `[]` for non-`local` entries: unverified peer digests are never re-served), `createReadStream(id, range?)` (local blobs only, inclusive `BlobRange`), `setPinned(id, pinned)`, and `delete(id)`.
+Every method canonicalizes `id` first and throws `InvalidBlobIDError` when it is invalid.
+`delete` removes the row (manifest and transfer rows cascade), aborts any transfer staging area, then deletes the bytes.
+
+## Peer transfer
+
+- `beginFetch(id, { contentLength, chunkSize, chunks, contentType?, encrypted?, keyID? })` validates the untrusted manifest (`InvalidManifestError`) against the ID and limits, then records the entry as `partial` with a fresh staging ID. A local blob is a no-op; an identical manifest with live staging is idempotent; a different one resets the transfer first. An existing stub whose stored `contentLength` differs from the manifest throws `InvalidManifestError`. A zero-length blob records the service's `chunkSize`, not the peer's.
+- `getPresentChunks(id)` lists staged indexes for resume. If the staging area vanished, the transfer is reset and the list is empty.
+- `stageChunk({ id, index, bytes })` checks length (`ChunkLengthError`) and digest (`ChunkDigestMismatchError`) before writing.
+- `completeFetch(id)` throws `TransferIncompleteError` while chunks are missing. It verifies length and whole-blob digest from the staged bytes before committing; on mismatch it aborts staging, resets the transfer, and throws `BlobIDMismatchError`.
+
+## Staging maintenance
+
+`pruneStaging(olderThan)` returns `{ removed, failed }`. It skips areas modified after `olderThan`.
+Only areas with the service's own `w-` (write) and `t-` (transfer) ID prefixes are considered; other names are left untouched. A failure on one area (for example a backend abort error) is counted in `failed` and does not stop the others.
+Transfer areas are aborted and reset only if, under the blob lock, the session still points at that staging ID and is itself older than `olderThan`.
+Write areas are aborted unless they belong to a write in progress in this process. Writes in other processes are protected only by the age threshold: `olderThan` must exceed the longest upload duration.
+A backend without `listStaging` returns `{ removed: 0, failed: 0 }`.
+The backend's staging namespace must not be shared with non-service writers that use `w-`/`t-` IDs: such areas would be pruned.
+Abandoned `remote-only` stub rows (for example after a reset) are never removed automatically; there is no garbage collection for them.
+
+## Locking
+
+`BlobLock` is `withLock(id, fn)`, keyed by canonical blob ID.
+Lock order is always blob lock, then store transaction. Locks are non-reentrant: public methods take the lock once and call unlocked helpers.
+`write` (commit and record), `delete`, `setPinned`, `beginFetch`, `stageChunk`, `completeFetch`, transfer resets, and pruning of a transfer area run under the lock.
+
+- `createMemoryBlobLock()` (default): in-process keyed mutex, correct for a single process.
+- `createFileBlobLock({ directory, acquireTimeoutMs? })`: from `@hozon/blob-node-fs`: cross-process lock for processes on one host sharing storage, one lock file per ID. `directory` must be on a local filesystem. Exclusion is as strong as `@sozai/lock` provides; its stale-lock reaping has a small documented exclusion gap.
+- Multi-host deployments sharing a backend and database need a distributed `BlobLock`. None ships; supply your own. A failed acquire throws `BlobLockTimeoutError`.
+
+## Store registration
+
+The caller must register `blobStoreDefinition` on the `HozonDB` before creating the service. The service does not register it.
+
+## Errors
+
+`BlobNotFoundError`, `BlobTooLargeError`, `BlobIDMismatchError`, `ContentTypeMismatchError`, `ChunkDigestMismatchError`, `ChunkLengthError`, `InvalidManifestError`, `InvalidRangeError`, `BlobWriteAbortedError`, `TransferIncompleteError`, and the re-exported `InvalidBlobIDError` and `BlobLockTimeoutError`.

package/lib/errors.d.ts

@@ -0,0 +1,52 @@
+export declare class BlobNotFoundError extends Error {
+    constructor(id: string, options?: ErrorOptions);
+}
+export declare class BlobTooLargeError extends Error {
+    constructor(limit: number, options?: ErrorOptions);
+}
+export type BlobIDMismatchErrorParams = {
+    expected: string;
+    actual: string;
+};
+export declare class BlobIDMismatchError extends Error {
+    constructor(params: BlobIDMismatchErrorParams, options?: ErrorOptions);
+}
+export type ContentTypeMismatchErrorParams = {
+    expected: string;
+    actual: string;
+};
+export declare class ContentTypeMismatchError extends Error {
+    constructor(params: ContentTypeMismatchErrorParams, options?: ErrorOptions);
+}
+export type ChunkDigestMismatchErrorParams = {
+    id: string;
+    index: number;
+};
+export declare class ChunkDigestMismatchError extends Error {
+    constructor(params: ChunkDigestMismatchErrorParams, options?: ErrorOptions);
+}
+export type ChunkLengthErrorParams = {
+    id: string;
+    index: number;
+    expected: number;
+    actual: number;
+};
+export declare class ChunkLengthError extends Error {
+    constructor(params: ChunkLengthErrorParams, options?: ErrorOptions);
+}
+export declare class InvalidManifestError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class InvalidRangeError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class BlobWriteAbortedError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export type TransferIncompleteErrorParams = {
+    id: string;
+    missing: number;
+};
+export declare class TransferIncompleteError extends Error {
+    constructor(params: TransferIncompleteErrorParams, options?: ErrorOptions);
+}

package/lib/errors.js

@@ -0,0 +1,60 @@
+export class BlobNotFoundError extends Error {
+    constructor(id, options){
+        super(`Blob not found: ${id}`, options);
+        this.name = 'BlobNotFoundError';
+    }
+}
+export class BlobTooLargeError extends Error {
+    constructor(limit, options){
+        super(`Blob exceeds the size limit of ${limit} bytes`, options);
+        this.name = 'BlobTooLargeError';
+    }
+}
+export class BlobIDMismatchError extends Error {
+    constructor(params, options){
+        super(`Blob ID mismatch: expected ${params.expected}, got ${params.actual}`, options);
+        this.name = 'BlobIDMismatchError';
+    }
+}
+export class ContentTypeMismatchError extends Error {
+    constructor(params, options){
+        super(`Content type mismatch: expected ${JSON.stringify(params.expected)}, got ${JSON.stringify(params.actual)}`, options);
+        this.name = 'ContentTypeMismatchError';
+    }
+}
+export class ChunkDigestMismatchError extends Error {
+    constructor(params, options){
+        super(`Chunk ${params.index} of blob ${params.id} does not match its manifest digest`, options);
+        this.name = 'ChunkDigestMismatchError';
+    }
+}
+export class ChunkLengthError extends Error {
+    constructor(params, options){
+        super(`Chunk ${params.index} of blob ${params.id} must be ${params.expected} bytes, got ${params.actual}`, options);
+        this.name = 'ChunkLengthError';
+    }
+}
+export class InvalidManifestError extends Error {
+    constructor(message, options){
+        super(`Invalid manifest: ${message}`, options);
+        this.name = 'InvalidManifestError';
+    }
+}
+export class InvalidRangeError extends Error {
+    constructor(message, options){
+        super(`Invalid range: ${message}`, options);
+        this.name = 'InvalidRangeError';
+    }
+}
+export class BlobWriteAbortedError extends Error {
+    constructor(message = 'Blob write aborted', options){
+        super(message, options);
+        this.name = 'BlobWriteAbortedError';
+    }
+}
+export class TransferIncompleteError extends Error {
+    constructor(params, options){
+        super(`Cannot complete transfer of ${params.id}: ${params.missing} chunk(s) missing`, options);
+        this.name = 'TransferIncompleteError';
+    }
+}

package/lib/fresh.d.ts

@@ -0,0 +1,2 @@
+import type { BlobEntry, BlobStoreAPI } from '@hozon/store-blob';
+export declare function getFreshEntry(store: BlobStoreAPI, blobID: string): Promise<BlobEntry | null>;

package/lib/fresh.js

@@ -0,0 +1,6 @@
+// A scope remembers getEntry results; reads made under the blob lock must see the current row.
+export async function getFreshEntry(store, blobID) {
+    return (await store.getEntries([
+        blobID
+    ])).get(blobID) ?? null;
+}

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+export { BlobLockTimeoutError } from '@hozon/blob-backend';
+export { InvalidBlobIDError } from '@hozon/blob-id';
+export { InvalidCursorError } from '@hozon/store-blob';
+export { BlobIDMismatchError, type BlobIDMismatchErrorParams, BlobNotFoundError, BlobTooLargeError, BlobWriteAbortedError, ChunkDigestMismatchError, type ChunkDigestMismatchErrorParams, ChunkLengthError, type ChunkLengthErrorParams, ContentTypeMismatchError, type ContentTypeMismatchErrorParams, InvalidManifestError, InvalidRangeError, TransferIncompleteError, type TransferIncompleteErrorParams, } from './errors.js';
+export { type BlobLimits, DEFAULT_CHUNK_SIZE, DEFAULT_LIMITS } from './limits.js';
+export { type BlobService, type BlobServiceParams, createBlobService } from './service.js';
+export type { StageChunkParams, TransferManifest } from './transfer.js';
+export type { WriteOptions, WriteParams, WriteResult } from './write.js';

package/lib/index.js

@@ -0,0 +1,6 @@
+export { BlobLockTimeoutError } from '@hozon/blob-backend';
+export { InvalidBlobIDError } from '@hozon/blob-id';
+export { InvalidCursorError } from '@hozon/store-blob';
+export { BlobIDMismatchError, BlobNotFoundError, BlobTooLargeError, BlobWriteAbortedError, ChunkDigestMismatchError, ChunkLengthError, ContentTypeMismatchError, InvalidManifestError, InvalidRangeError, TransferIncompleteError } from './errors.js';
+export { DEFAULT_CHUNK_SIZE, DEFAULT_LIMITS } from './limits.js';
+export { createBlobService } from './service.js';

package/lib/limits.d.ts

@@ -0,0 +1,9 @@
+export type BlobLimits = {
+    maxBlobSize: number;
+    maxChunkSize: number;
+    minChunkSize: number;
+};
+export declare const DEFAULT_CHUNK_SIZE: number;
+export declare const DEFAULT_LIMITS: BlobLimits;
+export declare function resolveLimits(limits?: Partial<BlobLimits>): BlobLimits;
+export declare function assertChunkSize(chunkSize: number, limits: BlobLimits): void;

package/lib/limits.js

@@ -0,0 +1,25 @@
+export const DEFAULT_CHUNK_SIZE = 1024 * 1024;
+export const DEFAULT_LIMITS = {
+    maxBlobSize: 1024 * 1024 * 1024,
+    maxChunkSize: 16 * 1024 * 1024,
+    minChunkSize: 1024
+};
+function isPositiveInteger(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}
+export function resolveLimits(limits = {}) {
+    const resolved = {
+        maxBlobSize: limits.maxBlobSize ?? DEFAULT_LIMITS.maxBlobSize,
+        maxChunkSize: limits.maxChunkSize ?? DEFAULT_LIMITS.maxChunkSize,
+        minChunkSize: limits.minChunkSize ?? DEFAULT_LIMITS.minChunkSize
+    };
+    if (!Number.isSafeInteger(resolved.maxBlobSize) || resolved.maxBlobSize < 0 || !isPositiveInteger(resolved.minChunkSize) || !isPositiveInteger(resolved.maxChunkSize) || resolved.minChunkSize > resolved.maxChunkSize) {
+        throw new Error('Invalid limits');
+    }
+    return resolved;
+}
+export function assertChunkSize(chunkSize, limits) {
+    if (!Number.isSafeInteger(chunkSize) || chunkSize < limits.minChunkSize || chunkSize > limits.maxChunkSize) {
+        throw new Error('Invalid chunkSize');
+    }
+}

package/lib/manage.d.ts

@@ -0,0 +1,11 @@
+import type { BlobBackend, BlobLock } from '@hozon/blob-backend';
+import type { BlobIDCodec } from '@hozon/blob-id';
+import type { StoreProvider } from '@hozon/db';
+export type ManageContext = {
+    db: StoreProvider;
+    backend: BlobBackend;
+    codec: BlobIDCodec;
+    lock: BlobLock;
+};
+export declare function setBlobPinned(ctx: ManageContext, id: string, pinned: boolean): Promise<void>;
+export declare function deleteBlob(ctx: ManageContext, id: string): Promise<boolean>;

package/lib/manage.js

@@ -0,0 +1,31 @@
+import { getBlobStore } from '@hozon/store-blob';
+import { BlobNotFoundError } from './errors.js';
+import { getFreshEntry } from './fresh.js';
+export async function setBlobPinned(ctx, id, pinned) {
+    const blobID = ctx.codec.canonicalize(id);
+    await ctx.lock.withLock(blobID, async ()=>{
+        const store = await getBlobStore(ctx.db);
+        if (await getFreshEntry(store, blobID) === null) throw new BlobNotFoundError(blobID);
+        await store.setPinned(blobID, pinned);
+    });
+}
+export async function deleteBlob(ctx, id) {
+    const blobID = ctx.codec.canonicalize(id);
+    return await ctx.lock.withLock(blobID, async ()=>{
+        const store = await getBlobStore(ctx.db);
+        const entry = await getFreshEntry(store, blobID);
+        if (entry === null) return false;
+        const transfer = entry.state === 'partial' ? await store.getTransfer(blobID) : null;
+        // The row goes first: a crash then leaves orphaned bytes, never a row without bytes.
+        await store.deleteEntry(blobID);
+        if (transfer !== null) {
+            try {
+                await ctx.backend.abortStaging(transfer.stagingID);
+            } catch  {
+            // Reclaimed by staging pruning.
+            }
+        }
+        if (entry.state === 'local') await ctx.backend.delete(blobID);
+        return true;
+    });
+}

package/lib/prune.d.ts

@@ -0,0 +1,5 @@
+import type { WriteContext } from './write.js';
+export declare function pruneStaging(ctx: WriteContext, olderThan: Date): Promise<{
+    removed: number;
+    failed: number;
+}>;

package/lib/prune.js

@@ -0,0 +1,56 @@
+import { getBlobStore } from '@hozon/store-blob';
+// Removes abandoned staging areas last modified before `olderThan`. Only areas
+// with this service's `w-` and `t-` ID prefixes are considered. A failure on one
+// area is counted in `failed` and does not stop the others.
+export async function pruneStaging(ctx, olderThan) {
+    if (ctx.backend.listStaging === undefined) return {
+        removed: 0,
+        failed: 0
+    };
+    const cutoff = olderThan.getTime();
+    const store = await getBlobStore(ctx.db);
+    let removed = 0;
+    let failed = 0;
+    // Collect first: aborting while iterating could disturb the backend's listing.
+    const old = [];
+    for await (const area of ctx.backend.listStaging()){
+        if (!isOwnedStagingID(area.stagingID)) continue;
+        if (area.modifiedAt.getTime() < cutoff) old.push(area.stagingID);
+    }
+    for (const stagingID of old){
+        try {
+            const session = await store.getTransferByStagingID(stagingID);
+            if (session === null) {
+                // Write staging IDs are random and never reused, so a flag check is enough.
+                // Other processes' writes are protected by the age threshold.
+                if (ctx.activeWrites.has(stagingID)) continue;
+                await ctx.backend.abortStaging(stagingID);
+                removed++;
+                continue;
+            }
+            if (session.updatedAt >= cutoff) continue;
+            // One lock acquisition per transfer area; the session is re-read under it
+            // because a chunk may have been staged since the listing.
+            const pruned = await ctx.lock.withLock(session.blobID, async ()=>{
+                const locked = await getBlobStore(ctx.db);
+                const current = await locked.getTransfer(session.blobID);
+                if (current === null || current.stagingID !== stagingID || current.updatedAt >= cutoff) {
+                    return false;
+                }
+                await ctx.backend.abortStaging(stagingID);
+                await locked.resetTransfer(session.blobID);
+                return true;
+            });
+            if (pruned) removed++;
+        } catch  {
+            failed++;
+        }
+    }
+    return {
+        removed,
+        failed
+    };
+}
+function isOwnedStagingID(stagingID) {
+    return stagingID.startsWith('w-') || stagingID.startsWith('t-');
+}

package/lib/read.d.ts

@@ -0,0 +1,20 @@
+import type { BlobBackend, BlobRange } from '@hozon/blob-backend';
+import type { BlobIDCodec } from '@hozon/blob-id';
+import type { StoreProvider } from '@hozon/db';
+import type { BlobEntry } from '@hozon/store-blob';
+export type ReadContext = {
+    db: StoreProvider;
+    backend: BlobBackend;
+    codec: BlobIDCodec;
+};
+export declare function getEntry(ctx: ReadContext, id: string): Promise<BlobEntry | null>;
+export declare function listEntries(ctx: ReadContext, params: {
+    limit: number;
+    cursor?: string;
+}): Promise<{
+    entries: Array<BlobEntry>;
+    nextCursor: string | null;
+}>;
+export declare function hasBlob(ctx: ReadContext, id: string): Promise<boolean>;
+export declare function getChunkDigests(ctx: ReadContext, id: string): Promise<Array<Uint8Array>>;
+export declare function createBlobReadStream(ctx: ReadContext, id: string, range?: BlobRange): Promise<ReadableStream<Uint8Array>>;

package/lib/read.js

@@ -0,0 +1,37 @@
+import { getBlobStore } from '@hozon/store-blob';
+import { BlobNotFoundError, InvalidRangeError } from './errors.js';
+export async function getEntry(ctx, id) {
+    const store = await getBlobStore(ctx.db);
+    return await store.getEntry(ctx.codec.canonicalize(id));
+}
+export async function listEntries(ctx, params) {
+    const store = await getBlobStore(ctx.db);
+    return await store.listEntries(params);
+}
+export async function hasBlob(ctx, id) {
+    return (await getEntry(ctx, id))?.state === 'local';
+}
+export async function getChunkDigests(ctx, id) {
+    const blobID = ctx.codec.canonicalize(id);
+    const store = await getBlobStore(ctx.db);
+    // Digests of non-local entries come from an unverified peer manifest.
+    const entry = await store.getEntry(blobID);
+    if (entry?.state !== 'local') return [];
+    return await store.getChunkDigests(blobID);
+}
+export async function createBlobReadStream(ctx, id, range) {
+    const blobID = ctx.codec.canonicalize(id);
+    const store = await getBlobStore(ctx.db);
+    const entry = await store.getEntry(blobID);
+    if (entry === null || entry.state !== 'local') throw new BlobNotFoundError(blobID);
+    if (range !== undefined) {
+        const { start, end } = range;
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || start > end) {
+            throw new InvalidRangeError(`bytes ${start}-${end}`);
+        }
+        if (end >= entry.contentLength) {
+            throw new InvalidRangeError(`end ${end} is beyond content length ${entry.contentLength}`);
+        }
+    }
+    return await ctx.backend.createReadStream(blobID, range);
+}

package/lib/service.d.ts

@@ -0,0 +1,49 @@
+import type { BlobBackend, BlobLock, BlobRange } from '@hozon/blob-backend';
+import type { BlobIDCodec } from '@hozon/blob-id';
+import type { StoreProvider } from '@hozon/db';
+import type { BlobEntry } from '@hozon/store-blob';
+import type { Runtime } from '@sozai/runtime';
+import { type BlobLimits } from './limits.js';
+import { type StageChunkParams, type TransferManifest } from './transfer.js';
+import { type WriteParams, type WriteResult } from './write.js';
+export type BlobServiceParams = {
+    db: StoreProvider;
+    backend: BlobBackend;
+    codec?: BlobIDCodec;
+    chunkSize?: number;
+    lock?: BlobLock;
+    limits?: Partial<BlobLimits>;
+    runtime?: Runtime;
+};
+export type BlobService = {
+    write(params: WriteParams): Promise<WriteResult>;
+    writeWith<T>(params: WriteParams & {
+        fn: (tx: StoreProvider, entry: BlobEntry) => Promise<T>;
+    }): Promise<WriteResult & {
+        result: T;
+    }>;
+    get(id: string): Promise<BlobEntry | null>;
+    list(params: {
+        limit: number;
+        cursor?: string;
+    }): Promise<{
+        entries: Array<BlobEntry>;
+        nextCursor: string | null;
+    }>;
+    has(id: string): Promise<boolean>;
+    getChunkDigests(id: string): Promise<Array<Uint8Array>>;
+    createReadStream(id: string, range?: BlobRange): Promise<ReadableStream<Uint8Array>>;
+    setPinned(id: string, pinned: boolean): Promise<void>;
+    delete(id: string): Promise<boolean>;
+    beginFetch(id: string, manifest: TransferManifest): Promise<void>;
+    getPresentChunks(id: string): Promise<Array<number>>;
+    stageChunk(params: StageChunkParams): Promise<void>;
+    completeFetch(id: string): Promise<BlobEntry>;
+    pruneStaging(olderThan: Date): Promise<{
+        removed: number;
+        failed: number;
+    }>;
+    readonly codec: BlobIDCodec;
+    readonly limits: BlobLimits;
+};
+export declare function createBlobService(params: BlobServiceParams): BlobService;

package/lib/service.js

@@ -0,0 +1,55 @@
+import { createMemoryBlobLock } from '@hozon/blob-backend';
+import { blake3Codec } from '@hozon/blob-id';
+import { createRuntime } from '@sozai/runtime';
+import { assertChunkSize, DEFAULT_CHUNK_SIZE, resolveLimits } from './limits.js';
+import { deleteBlob, setBlobPinned } from './manage.js';
+import { pruneStaging } from './prune.js';
+import { createBlobReadStream, getChunkDigests, getEntry, hasBlob, listEntries } from './read.js';
+import { beginFetch, completeFetch, getPresentChunks, stageChunk } from './transfer.js';
+import { writeBlob } from './write.js';
+export function createBlobService(params) {
+    const limits = resolveLimits(params.limits);
+    const chunkSize = params.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    assertChunkSize(chunkSize, limits);
+    const ctx = {
+        db: params.db,
+        backend: params.backend,
+        codec: params.codec ?? blake3Codec,
+        chunkSize,
+        lock: params.lock ?? createMemoryBlobLock(),
+        limits: Object.freeze(limits),
+        runtime: params.runtime ?? createRuntime(),
+        activeWrites: new Set()
+    };
+    return {
+        codec: ctx.codec,
+        limits: ctx.limits,
+        get: (id)=>getEntry(ctx, id),
+        list: (listParams)=>listEntries(ctx, listParams),
+        has: (id)=>hasBlob(ctx, id),
+        getChunkDigests: (id)=>getChunkDigests(ctx, id),
+        createReadStream: (id, range)=>createBlobReadStream(ctx, id, range),
+        setPinned: (id, pinned)=>setBlobPinned(ctx, id, pinned),
+        delete: (id)=>deleteBlob(ctx, id),
+        beginFetch: (id, manifest)=>beginFetch(ctx, id, manifest),
+        getPresentChunks: (id)=>getPresentChunks(ctx, id),
+        stageChunk: (params)=>stageChunk(ctx, params),
+        completeFetch: (id)=>completeFetch(ctx, id),
+        pruneStaging: (olderThan)=>pruneStaging(ctx, olderThan),
+        async write (params) {
+            const { entry, created } = await writeBlob(ctx, params);
+            return {
+                entry,
+                created
+            };
+        },
+        async writeWith (params) {
+            const { entry, created, result } = await writeBlob(ctx, params);
+            return {
+                entry,
+                created,
+                result: result
+            };
+        }
+    };
+}

package/lib/transfer.d.ts

@@ -0,0 +1,32 @@
+import type { BlobBackend, BlobLock } from '@hozon/blob-backend';
+import type { BlobIDCodec } from '@hozon/blob-id';
+import type { StoreProvider } from '@hozon/db';
+import type { BlobEntry } from '@hozon/store-blob';
+import type { Runtime } from '@sozai/runtime';
+import type { BlobLimits } from './limits.js';
+export type TransferManifest = {
+    contentLength: number;
+    chunkSize: number;
+    chunks: Array<Uint8Array>;
+    contentType?: string;
+    encrypted?: boolean;
+    keyID?: string;
+};
+export type StageChunkParams = {
+    id: string;
+    index: number;
+    bytes: Uint8Array;
+};
+export type TransferContext = {
+    db: StoreProvider;
+    backend: BlobBackend;
+    codec: BlobIDCodec;
+    chunkSize: number;
+    lock: BlobLock;
+    limits: BlobLimits;
+    runtime: Runtime;
+};
+export declare function beginFetch(ctx: TransferContext, id: string, manifest: TransferManifest): Promise<void>;
+export declare function getPresentChunks(ctx: TransferContext, id: string): Promise<Array<number>>;
+export declare function stageChunk(ctx: TransferContext, params: StageChunkParams): Promise<void>;
+export declare function completeFetch(ctx: TransferContext, id: string): Promise<BlobEntry>;

package/lib/transfer.js

@@ -0,0 +1,297 @@
+import { getBlobStore } from '@hozon/store-blob';
+import { BlobIDMismatchError, BlobNotFoundError, ChunkDigestMismatchError, ChunkLengthError, InvalidManifestError, TransferIncompleteError } from './errors.js';
+import { getFreshEntry } from './fresh.js';
+import { createStagingID } from './write.js';
+function bytesEqual(a, b) {
+    if (a.length !== b.length) return false;
+    for(let i = 0; i < a.length; i++){
+        if (a[i] !== b[i]) return false;
+    }
+    return true;
+}
+function digestsEqual(a, b) {
+    return a.length === b.length && a.every((digest, i)=>bytesEqual(digest, b[i]));
+}
+function isSafeNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function chunkCount(contentLength, chunkSize) {
+    return contentLength === 0 ? 0 : Math.ceil(contentLength / chunkSize);
+}
+// Expected length of chunk `index`: `chunkSize`, or the remainder for the last chunk.
+function chunkLength(entry, count, index) {
+    return index < count - 1 ? entry.chunkSize : entry.contentLength - (count - 1) * entry.chunkSize;
+}
+// Returns the content type to record: the manifest's, or the one embedded in the ID.
+function validateManifest(ctx, blobID, manifest) {
+    const { contentLength, chunkSize, chunks } = manifest;
+    if (!isSafeNonNegativeInteger(contentLength)) {
+        throw new InvalidManifestError(`contentLength ${contentLength} is not a non-negative integer`);
+    }
+    if (!isSafeNonNegativeInteger(chunkSize)) {
+        throw new InvalidManifestError(`chunkSize ${chunkSize} is not a non-negative integer`);
+    }
+    // A zero-length blob has no chunks, so its chunk size is not constrained.
+    if (contentLength > 0 && (chunkSize < ctx.limits.minChunkSize || chunkSize > ctx.limits.maxChunkSize)) {
+        throw new InvalidManifestError(`chunkSize ${chunkSize} is outside [${ctx.limits.minChunkSize}, ${ctx.limits.maxChunkSize}]`);
+    }
+    if (contentLength > ctx.limits.maxBlobSize) {
+        throw new InvalidManifestError(`contentLength ${contentLength} exceeds the size limit of ${ctx.limits.maxBlobSize} bytes`);
+    }
+    const expectedCount = chunkCount(contentLength, chunkSize);
+    if (!Array.isArray(chunks) || chunks.length !== expectedCount) {
+        throw new InvalidManifestError(`expected ${expectedCount} chunk digest(s)`);
+    }
+    for (const [index, digest] of chunks.entries()){
+        if (!(digest instanceof Uint8Array) || digest.length !== ctx.codec.digestLength) {
+            throw new InvalidManifestError(`chunk ${index} digest must be ${ctx.codec.digestLength} bytes`);
+        }
+    }
+    const { contentType, encrypted, keyID } = manifest;
+    if (contentType !== undefined && (typeof contentType !== 'string' || contentType.length > 255)) {
+        throw new InvalidManifestError('contentType must be a string of at most 255 characters');
+    }
+    if (encrypted !== undefined && typeof encrypted !== 'boolean') {
+        throw new InvalidManifestError('encrypted must be a boolean');
+    }
+    if (keyID !== undefined && (typeof keyID !== 'string' || keyID.length > 255)) {
+        throw new InvalidManifestError('keyID must be a string of at most 255 characters');
+    }
+    const decoded = ctx.codec.decode(blobID);
+    if (decoded.contentLength !== contentLength) {
+        throw new InvalidManifestError(`contentLength ${contentLength} does not match the ID (${decoded.contentLength})`);
+    }
+    if (decoded.contentType === undefined) return manifest.contentType;
+    if (manifest.contentType !== undefined && manifest.contentType !== decoded.contentType) {
+        throw new InvalidManifestError(`contentType ${JSON.stringify(manifest.contentType)} does not match the ID (${JSON.stringify(decoded.contentType)})`);
+    }
+    return decoded.contentType;
+}
+async function abortQuietly(backend, stagingID) {
+    try {
+        await backend.abortStaging(stagingID);
+    } catch  {
+    // Reclaimed by staging pruning.
+    }
+}
+// Whether the staging area of a session with staged chunks still exists.
+// Backends create staging lazily, so a session without chunks has no area yet.
+async function stagingExists(backend, transfer, chunkSize) {
+    const first = transfer.presentChunks[0];
+    if (first === undefined) return true;
+    const start = first * chunkSize;
+    let probe;
+    try {
+        probe = await backend.createStagingReadStream(transfer.stagingID, {
+            start,
+            end: start
+        });
+    } catch  {
+        return false;
+    }
+    try {
+        await probe.cancel();
+    } catch  {
+    // The probe only needed to open.
+    }
+    return true;
+}
+// Lock held: the transfer of a `partial` entry, or BlobNotFoundError.
+async function requireTransfer(ctx, blobID) {
+    const store = await getBlobStore(ctx.db);
+    const entry = await getFreshEntry(store, blobID);
+    const transfer = entry?.state === 'partial' ? await store.getTransfer(blobID) : null;
+    if (entry === null || transfer === null) {
+        throw new BlobNotFoundError(blobID, {
+            cause: new Error('No active transfer')
+        });
+    }
+    return {
+        store,
+        entry,
+        transfer,
+        digests: await store.getChunkDigests(blobID)
+    };
+}
+export async function beginFetch(ctx, id, manifest) {
+    const blobID = ctx.codec.canonicalize(id);
+    const contentType = validateManifest(ctx, blobID, manifest);
+    // A zero-length blob has no chunks, so the peer's chunk size is meaningless.
+    const chunkSize = manifest.contentLength === 0 ? ctx.chunkSize : manifest.chunkSize;
+    await ctx.lock.withLock(blobID, async ()=>{
+        const store = await getBlobStore(ctx.db);
+        const entry = await getFreshEntry(store, blobID);
+        if (entry?.state === 'local') return;
+        // A stub with another length could never complete against this manifest.
+        if (entry !== null && entry.contentLength !== manifest.contentLength) {
+            throw new InvalidManifestError(`contentLength ${manifest.contentLength} does not match the stored entry (${entry.contentLength})`);
+        }
+        const transfer = entry === null ? null : await store.getTransfer(blobID);
+        if (entry !== null && transfer !== null) {
+            const identical = entry.state === 'partial' && entry.chunkSize === chunkSize && digestsEqual(await store.getChunkDigests(blobID), manifest.chunks);
+            if (identical && await stagingExists(ctx.backend, transfer, entry.chunkSize)) {
+                await store.touchTransfer(blobID);
+                return;
+            }
+            await abortQuietly(ctx.backend, transfer.stagingID);
+        }
+        if (entry === null) {
+            await store.insertEntry({
+                blobID,
+                contentLength: manifest.contentLength,
+                encrypted: manifest.encrypted ?? false,
+                keyID: manifest.keyID ?? null,
+                chunkSize,
+                state: 'remote-only',
+                createdAt: Date.now(),
+                contentType: contentType ?? null
+            }, []);
+        } else {
+            // Drops the previous manifest and progress so the new manifest replaces them.
+            await store.resetTransfer(blobID);
+            if (contentType !== undefined) await store.fillContentType(blobID, contentType);
+        }
+        const chunks = manifest.chunks.map((digest, index)=>({
+                index,
+                digest
+            }));
+        await store.beginTransfer({
+            blobID,
+            chunkSize,
+            chunks,
+            stagingID: createStagingID(ctx.runtime, 't')
+        });
+    });
+}
+export async function getPresentChunks(ctx, id) {
+    const blobID = ctx.codec.canonicalize(id);
+    return await ctx.lock.withLock(blobID, async ()=>{
+        const store = await getBlobStore(ctx.db);
+        const entry = await getFreshEntry(store, blobID);
+        if (entry?.state !== 'partial') return [];
+        const transfer = await store.getTransfer(blobID);
+        if (transfer === null) return [];
+        if (!await stagingExists(ctx.backend, transfer, entry.chunkSize)) {
+            await store.resetTransfer(blobID);
+            return [];
+        }
+        return transfer.presentChunks;
+    });
+}
+export async function stageChunk(ctx, params) {
+    const { id, index, bytes } = params;
+    const blobID = ctx.codec.canonicalize(id);
+    await ctx.lock.withLock(blobID, async ()=>{
+        const { store, entry, transfer, digests } = await requireTransfer(ctx, blobID);
+        if (!Number.isSafeInteger(index) || index < 0 || index >= digests.length) {
+            throw new InvalidManifestError(`chunk index ${index} is outside [0, ${digests.length})`);
+        }
+        const expectedLength = chunkLength(entry, digests.length, index);
+        if (bytes.length !== expectedLength) {
+            throw new ChunkLengthError({
+                id: blobID,
+                index,
+                expected: expectedLength,
+                actual: bytes.length
+            });
+        }
+        const hasher = ctx.codec.createHasher();
+        hasher.update(bytes);
+        if (!bytesEqual(hasher.digest(), digests[index])) {
+            throw new ChunkDigestMismatchError({
+                id: blobID,
+                index
+            });
+        }
+        await ctx.backend.writeChunk(transfer.stagingID, index * entry.chunkSize, bytes);
+        await store.recordTransferChunk(blobID, index);
+    });
+}
+// Streams staged bytes through the hasher; never buffers the whole blob.
+async function hashStaging(ctx, stream, limit) {
+    const reader = stream.getReader();
+    const hasher = ctx.codec.createHasher();
+    let length = 0;
+    try {
+        while(true){
+            const { done, value } = await reader.read();
+            if (done) break;
+            length += value.length;
+            // Already a mismatch; stop reading.
+            if (length > limit) {
+                await reader.cancel();
+                break;
+            }
+            hasher.update(value);
+        }
+    } finally{
+        reader.releaseLock();
+    }
+    return {
+        digest: hasher.digest(),
+        length
+    };
+}
+export async function completeFetch(ctx, id) {
+    const blobID = ctx.codec.canonicalize(id);
+    return await ctx.lock.withLock(blobID, async ()=>{
+        const { store, entry, transfer, digests } = await requireTransfer(ctx, blobID);
+        const present = new Set(transfer.presentChunks);
+        const missing = digests.length - digests.filter((_, index)=>present.has(index)).length;
+        if (missing > 0) {
+            throw new TransferIncompleteError({
+                id: blobID,
+                missing
+            });
+        }
+        // A zero-length blob stages no chunks; materialize its empty area for commit.
+        if (digests.length === 0) {
+            await ctx.backend.writeChunk(transfer.stagingID, 0, new Uint8Array(0));
+        }
+        const expected = ctx.codec.decode(blobID);
+        let stream;
+        try {
+            stream = await ctx.backend.createStagingReadStream(transfer.stagingID);
+        } catch (cause) {
+            // The staging area vanished: the caller must begin again.
+            await store.resetTransfer(blobID);
+            throw new BlobNotFoundError(blobID, {
+                cause
+            });
+        }
+        const hashed = await hashStaging(ctx, stream, expected.contentLength);
+        if (hashed.length !== expected.contentLength || !bytesEqual(hashed.digest, expected.digest)) {
+            await abortQuietly(ctx.backend, transfer.stagingID);
+            await store.resetTransfer(blobID);
+            const actual = ctx.codec.encode({
+                digest: hashed.digest,
+                contentLength: hashed.length,
+                ...expected.contentType === undefined ? {} : {
+                    contentType: expected.contentType
+                }
+            });
+            throw new BlobIDMismatchError({
+                expected: blobID,
+                actual
+            });
+        }
+        // Verified: bytes are committed before the row.
+        await ctx.backend.commit(transfer.stagingID, blobID);
+        await store.promoteEntry({
+            blobID,
+            contentLength: entry.contentLength,
+            encrypted: entry.encrypted,
+            keyID: entry.keyID,
+            chunkSize: entry.chunkSize,
+            pinned: entry.pinned,
+            createdAt: entry.createdAt,
+            contentType: entry.contentType
+        }, digests.map((digest, index)=>({
+                index,
+                digest
+            })));
+        const promoted = await getFreshEntry(store, blobID);
+        if (promoted === null) throw new Error(`Blob entry ${blobID} missing after promotion`);
+        return promoted;
+    });
+}

package/lib/write.d.ts

@@ -0,0 +1,38 @@
+import type { BlobBackend, BlobLock } from '@hozon/blob-backend';
+import type { BlobIDCodec } from '@hozon/blob-id';
+import type { StoreProvider } from '@hozon/db';
+import type { BlobEntry } from '@hozon/store-blob';
+import type { Runtime } from '@sozai/runtime';
+import type { BlobLimits } from './limits.js';
+export type WriteOptions = {
+    contentType?: string;
+    encrypted?: boolean;
+    keyID?: string;
+    expectedID?: string;
+    maxSize?: number;
+    signal?: AbortSignal;
+};
+export type WriteParams = WriteOptions & {
+    stream: ReadableStream<Uint8Array>;
+};
+export type WriteResult = {
+    entry: BlobEntry;
+    created: boolean;
+};
+export type WriteContext = {
+    db: StoreProvider;
+    backend: BlobBackend;
+    codec: BlobIDCodec;
+    chunkSize: number;
+    lock: BlobLock;
+    limits: BlobLimits;
+    runtime: Runtime;
+    activeWrites: Set<string>;
+};
+export type RecordFn<T> = (tx: StoreProvider, entry: BlobEntry) => Promise<T>;
+export declare function createStagingID(runtime: Runtime, prefix: 'w' | 't'): string;
+export declare function writeBlob<T>(ctx: WriteContext, params: WriteParams & {
+    fn?: RecordFn<T>;
+}): Promise<WriteResult & {
+    result: T | undefined;
+}>;

package/lib/write.js

@@ -0,0 +1,195 @@
+import { hashStream } from '@hozon/blob-id';
+import { getBlobStore } from '@hozon/store-blob';
+import { BlobIDMismatchError, BlobTooLargeError, BlobWriteAbortedError, ContentTypeMismatchError } from './errors.js';
+import { getFreshEntry } from './fresh.js';
+// Random staging ID: `prefix` (`w` for writes, `t` for transfers), a dash, 32 hex chars.
+export function createStagingID(runtime, prefix) {
+    const bytes = runtime.getRandomValues(new Uint8Array(16));
+    return `${prefix}-${Array.from(bytes, (byte)=>byte.toString(16).padStart(2, '0')).join('')}`;
+}
+function sizeLimiter(limit) {
+    let total = 0;
+    return new TransformStream({
+        transform (piece, controller) {
+            total += piece.length;
+            if (total > limit) throw new BlobTooLargeError(limit);
+            controller.enqueue(piece);
+        }
+    });
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) throw new BlobWriteAbortedError(undefined, {
+        cause: signal.reason
+    });
+}
+async function cancelQuietly(stream, reason) {
+    try {
+        await stream.cancel(reason);
+    } catch  {
+    // The caller's error matters more than a failed cancel.
+    }
+}
+// Records the blob under the lock, inside a transaction when `fn` is given.
+async function record(ctx, fn, step) {
+    if (fn === undefined) {
+        return {
+            entry: await step(await getBlobStore(ctx.db)),
+            result: undefined
+        };
+    }
+    return await ctx.db.withTransaction(async (tx)=>{
+        const store = await getBlobStore(tx);
+        const entry = await step(store);
+        return {
+            entry,
+            result: await fn(tx, entry)
+        };
+    });
+}
+export async function writeBlob(ctx, params) {
+    const { stream, fn, ...options } = params;
+    const { signal } = options;
+    if (options.contentType !== undefined && (typeof options.contentType !== 'string' || options.contentType.length > 255)) {
+        await cancelQuietly(stream, new Error('Invalid contentType'));
+        throw new Error('Invalid contentType');
+    }
+    if (options.maxSize !== undefined && (!Number.isSafeInteger(options.maxSize) || options.maxSize < 0)) {
+        await cancelQuietly(stream, new Error('Invalid maxSize'));
+        throw new Error('Invalid maxSize');
+    }
+    const limit = Math.min(options.maxSize ?? Number.POSITIVE_INFINITY, ctx.limits.maxBlobSize);
+    let contentType = options.contentType;
+    let expectedID;
+    // Step 1: validate the expected ID before reading the body.
+    try {
+        throwIfAborted(signal);
+        if (options.expectedID !== undefined) {
+            expectedID = ctx.codec.canonicalize(options.expectedID);
+            const expected = ctx.codec.decode(expectedID);
+            if (expected.contentType !== undefined) {
+                if (contentType === undefined) {
+                    contentType = expected.contentType;
+                } else if (contentType !== expected.contentType) {
+                    throw new ContentTypeMismatchError({
+                        expected: expected.contentType,
+                        actual: contentType
+                    });
+                }
+            }
+            if (expected.contentLength > limit) throw new BlobTooLargeError(limit);
+        }
+    } catch (error) {
+        await cancelQuietly(stream, error);
+        throw error;
+    }
+    // Step 2: stream into a fresh staging area while hashing.
+    const stagingID = createStagingID(ctx.runtime, 'w');
+    ctx.activeWrites.add(stagingID);
+    let staged = true;
+    const discardStaging = async ()=>{
+        if (!staged) return;
+        staged = false;
+        try {
+            await ctx.backend.abortStaging(stagingID);
+        } catch  {
+        // An orphaned staging area is reclaimed by staging pruning.
+        }
+    };
+    try {
+        let hashed;
+        try {
+            const sink = await ctx.backend.createStaging(stagingID);
+            const hasher = hashStream({
+                codec: ctx.codec,
+                chunkSize: ctx.chunkSize
+            });
+            await stream.pipeThrough(sizeLimiter(limit)).pipeThrough(hasher.transform).pipeTo(sink, signal === undefined ? {} : {
+                signal
+            });
+            hashed = await hasher.result;
+        } catch (error) {
+            // Releases the source when staging failed before the pipe started.
+            if (!stream.locked) await cancelQuietly(stream, error);
+            if (signal?.aborted) throw new BlobWriteAbortedError(undefined, {
+                cause: error
+            });
+            throw error;
+        }
+        // Step 3: derive the ID and check it against the expected one.
+        const blobID = ctx.codec.encode({
+            digest: hashed.digest,
+            contentLength: hashed.contentLength,
+            ...contentType === undefined ? {} : {
+                contentType
+            }
+        });
+        if (expectedID !== undefined && blobID !== expectedID) {
+            throw new BlobIDMismatchError({
+                expected: expectedID,
+                actual: blobID
+            });
+        }
+        // Step 4: commit bytes, then record the entry, under the blob lock.
+        return await ctx.lock.withLock(blobID, async ()=>{
+            throwIfAborted(signal);
+            const store = await getBlobStore(ctx.db);
+            const existing = await getFreshEntry(store, blobID);
+            if (existing?.state === 'local') {
+                await discardStaging();
+                // Existing metadata wins; only a null content type is filled in.
+                const fill = async (target)=>{
+                    if (existing.contentType !== null || contentType === undefined) return existing;
+                    await target.fillContentType(blobID, contentType);
+                    return await getFreshEntry(target, blobID) ?? existing;
+                };
+                const { entry, result } = await record(ctx, fn, fill);
+                return {
+                    entry,
+                    created: false,
+                    result
+                };
+            }
+            const transfer = existing === null ? null : await store.getTransfer(blobID);
+            // Step 5: bytes are committed before the row. Re-check: the awaits above may outlast an abort.
+            throwIfAborted(signal);
+            await ctx.backend.commit(stagingID, blobID);
+            staged = false;
+            const input = {
+                blobID,
+                contentLength: hashed.contentLength,
+                encrypted: options.encrypted ?? false,
+                keyID: options.keyID ?? null,
+                chunkSize: ctx.chunkSize,
+                createdAt: Date.now(),
+                contentType: contentType ?? null
+            };
+            const chunks = hashed.chunks.map((digest, index)=>({
+                    index,
+                    digest
+                }));
+            const promote = async (target)=>{
+                await target.promoteEntry(input, chunks);
+                const entry = await getFreshEntry(target, blobID);
+                if (entry === null) throw new Error(`Blob entry ${blobID} missing after promotion`);
+                return entry;
+            };
+            const { entry, result } = await record(ctx, fn, promote);
+            // The promoted entry no longer references the transfer's staging area.
+            if (transfer !== null) {
+                try {
+                    await ctx.backend.abortStaging(transfer.stagingID);
+                } catch  {
+                // Reclaimed by staging pruning.
+                }
+            }
+            return {
+                entry,
+                created: true,
+                result
+            };
+        });
+    } finally{
+        await discardStaging();
+        ctx.activeWrites.delete(stagingID);
+    }
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@hozon/blob",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Content-addressed blob service with verified writes for Hozon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TairuFramework/hozon.git",
+    "directory": "packages/blob"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@hozon/blob-backend": "^0.2.0",
+    "@hozon/blob-id": "^0.1.1",
+    "@hozon/db": "^0.3.0",
+    "@hozon/store-blob": "^0.2.2",
+    "@sozai/runtime": "^0.1.0"
+  },
+  "devDependencies": {
+    "@hozon/blob-node-fs": "^0.2.0",
+    "@hozon/node-sqlite": "^0.1.0",
+    "@sozai/codec": "^0.4.3",
+    "@types/node": "^26.6.5",
+    "del-cli": "^8.0.1",
+    "vitest": "5.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del-cli lib",
+    "build:js": "del-cli \"lib/**/*.js\" && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del-cli \"lib/**/*.d.ts\" \"lib/**/*.d.ts.map\" && tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --skipLibCheck --declarationMap false",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
 }