@antasphere/chassis-server 1.0.0

package/dist/state.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Process-local runtime state. This is NOT application state (which lives in
+ * Postgres per the statelessness invariant) — it is the lifecycle of this one
+ * replica: readiness for /readyz and the draining flag for graceful shutdown.
+ */
+export interface RuntimeState {
+    ready: boolean;
+    reason: string;
+    draining: boolean;
+    /**
+     * A fail-closed boot verdict (PRDCT-1809): when set, every route except
+     * liveness, readiness and metrics answers 503 `service_closed` with this
+     * reason. Readiness alone does not stop the API — the single-host
+     * deployment's healthcheck watches /healthz — so a boot that found
+     * something it must not serve (an erasure it could not replay) closes the
+     * surface itself until an operator resolves it and restarts.
+     */
+    closed: string | null;
+}
+export declare function createRuntimeState(): RuntimeState;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAEjD"}

package/dist/state.js

@@ -0,0 +1,4 @@
+export function createRuntimeState() {
+    return { ready: false, reason: 'booting', draining: false, closed: null };
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAoBA,MAAM,UAAU,kBAAkB;IAChC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC5E,CAAC"}

package/dist/storage/driver.d.ts

@@ -0,0 +1,38 @@
+import type { Readable } from 'node:stream';
+/**
+ * The storage seam. Postgres never holds file bytes; every write goes
+ * through a driver. `local` (default) writes under DATA_DIR — valid for
+ * single-replica deployments; `s3` covers MinIO self-hosted and AWS/R2/GCS
+ * interop in cloud. Presigned-URL methods are deliberately reserved for a
+ * later revision (through-app streaming is the v1 contract).
+ */
+export interface ByteRange {
+    /** Inclusive start offset. */
+    start: number;
+    /** Inclusive end offset. */
+    end: number;
+}
+export interface PutOptions {
+    contentType: string;
+    sizeBytes: number;
+}
+export interface HeadResult {
+    sizeBytes: number;
+}
+export interface StorageDriver {
+    readonly name: 'local' | 's3';
+    put(key: string, data: Readable, opts: PutOptions): Promise<void>;
+    getStream(key: string, range?: ByteRange): Promise<Readable>;
+    exists(key: string): Promise<boolean>;
+    head(key: string): Promise<HeadResult | null>;
+    delete(key: string): Promise<void>;
+    /** Boot probe: throw when the backing store is not writable. */
+    healthcheck(): Promise<void>;
+}
+/**
+ * Content-addressed key layout: `ws/<workspaceId>/<ab>/<sha256>`. The sha is
+ * validated against a strict hex pattern, so a key can never smuggle path
+ * traversal; the two-char shard keeps directories small at the 200GB target.
+ */
+export declare function blobKey(workspaceId: string, sha256: string): string;
+//# sourceMappingURL=driver.d.ts.map

package/dist/storage/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/storage/driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,gEAAgE;IAChE,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAID;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAInE"}

package/dist/storage/driver.js

@@ -0,0 +1,14 @@
+const SHA256_RE = /^[a-f0-9]{64}$/;
+/**
+ * Content-addressed key layout: `ws/<workspaceId>/<ab>/<sha256>`. The sha is
+ * validated against a strict hex pattern, so a key can never smuggle path
+ * traversal; the two-char shard keeps directories small at the 200GB target.
+ */
+export function blobKey(workspaceId, sha256) {
+    if (!SHA256_RE.test(sha256))
+        throw new Error('invalid sha256');
+    if (!/^[0-9a-f-]{36}$/.test(workspaceId))
+        throw new Error('invalid workspace id');
+    return `ws/${workspaceId}/${sha256.slice(0, 2)}/${sha256}`;
+}
+//# sourceMappingURL=driver.js.map

package/dist/storage/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../src/storage/driver.ts"],"names":[],"mappings":"AAoCA,MAAM,SAAS,GAAG,gBAAgB,CAAC;AAEnC;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,WAAmB,EAAE,MAAc;IACzD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAC/D,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,WAAW,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAClF,OAAO,MAAM,WAAW,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC;AAC7D,CAAC"}

package/dist/storage/factory.d.ts

@@ -0,0 +1,4 @@
+import type { Env } from '../env.js';
+import type { StorageDriver } from './driver.js';
+export declare function createStorageDriver(env: Pick<Env, 'STORAGE_DRIVER' | 'DATA_DIR' | 'S3_BUCKET' | 'S3_REGION' | 'S3_ENDPOINT' | 'S3_ACCESS_KEY_ID' | 'S3_SECRET_ACCESS_KEY' | 'S3_FORCE_PATH_STYLE'>): StorageDriver;
+//# sourceMappingURL=factory.d.ts.map

package/dist/storage/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/storage/factory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,IAAI,CACP,GAAG,EACD,gBAAgB,GAChB,UAAU,GACV,WAAW,GACX,WAAW,GACX,aAAa,GACb,kBAAkB,GAClB,sBAAsB,GACtB,qBAAqB,CACxB,GACA,aAAa,CAef"}

package/dist/storage/factory.js

@@ -0,0 +1,20 @@
+import { join } from 'node:path';
+import { LocalStorageDriver } from './local.js';
+import { S3StorageDriver } from './s3.js';
+export function createStorageDriver(env) {
+    if (env.STORAGE_DRIVER === 's3') {
+        if (!env.S3_BUCKET || !env.S3_ACCESS_KEY_ID || !env.S3_SECRET_ACCESS_KEY) {
+            throw new Error('STORAGE_DRIVER=s3 requires S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY');
+        }
+        return new S3StorageDriver({
+            bucket: env.S3_BUCKET,
+            region: env.S3_REGION ?? 'us-east-1',
+            endpoint: env.S3_ENDPOINT,
+            accessKeyId: env.S3_ACCESS_KEY_ID,
+            secretAccessKey: env.S3_SECRET_ACCESS_KEY,
+            forcePathStyle: env.S3_FORCE_PATH_STYLE
+        });
+    }
+    return new LocalStorageDriver(join(env.DATA_DIR, 'storage'));
+}
+//# sourceMappingURL=factory.js.map

package/dist/storage/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/storage/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,UAAU,mBAAmB,CACjC,GAUC;IAED,IAAI,GAAG,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;QAChC,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,GAAG,CAAC,gBAAgB,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC;YACzE,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;QAClG,CAAC;QACD,OAAO,IAAI,eAAe,CAAC;YACzB,MAAM,EAAE,GAAG,CAAC,SAAS;YACrB,MAAM,EAAE,GAAG,CAAC,SAAS,IAAI,WAAW;YACpC,QAAQ,EAAE,GAAG,CAAC,WAAW;YACzB,WAAW,EAAE,GAAG,CAAC,gBAAgB;YACjC,eAAe,EAAE,GAAG,CAAC,oBAAoB;YACzC,cAAc,EAAE,GAAG,CAAC,mBAAmB;SACxC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;AAC/D,CAAC"}

package/dist/storage/index.d.ts

@@ -0,0 +1,4 @@
+export { type StorageDriver, blobKey } from './driver.js';
+export { createStorageDriver } from './factory.js';
+export { LocalStorageDriver } from './local.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/storage/index.js

@@ -0,0 +1,4 @@
+export { blobKey } from './driver.js';
+export { createStorageDriver } from './factory.js';
+export { LocalStorageDriver } from './local.js';
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,OAAO,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/storage/local.d.ts

@@ -0,0 +1,21 @@
+import type { Readable } from 'node:stream';
+import type { ByteRange, HeadResult, PutOptions, StorageDriver } from './driver.js';
+/**
+ * Filesystem driver: blobs under `<root>/blobs`, writes staged in
+ * `<root>/.tmp` and renamed into place (atomic on one filesystem — both live
+ * under the same mount). Single-replica only, which is Profile A.
+ */
+export declare class LocalStorageDriver implements StorageDriver {
+    readonly name: "local";
+    private readonly blobRoot;
+    private readonly tmpRoot;
+    constructor(root: string);
+    private pathFor;
+    put(key: string, data: Readable, _opts: PutOptions): Promise<void>;
+    getStream(key: string, range?: ByteRange): Promise<Readable>;
+    exists(key: string): Promise<boolean>;
+    head(key: string): Promise<HeadResult | null>;
+    delete(key: string): Promise<void>;
+    healthcheck(): Promise<void>;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/storage/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/storage/local.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAOpF;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IACtD,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,IAAI,EAAE,MAAM;IAKxB,OAAO,CAAC,OAAO;IAMT,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAclE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IAY5D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAY7C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAMnC"}

package/dist/storage/local.js

@@ -0,0 +1,88 @@
+import { createWriteStream } from 'node:fs';
+import { mkdir, open, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, normalize, sep } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { randomUUID } from 'node:crypto';
+/** A missing file — the only fs error head()/delete() treats as "absent". */
+function isEnoent(err) {
+    return err?.code === 'ENOENT';
+}
+/**
+ * Filesystem driver: blobs under `<root>/blobs`, writes staged in
+ * `<root>/.tmp` and renamed into place (atomic on one filesystem — both live
+ * under the same mount). Single-replica only, which is Profile A.
+ */
+export class LocalStorageDriver {
+    name = 'local';
+    blobRoot;
+    tmpRoot;
+    constructor(root) {
+        this.blobRoot = join(root, 'blobs');
+        this.tmpRoot = join(root, '.tmp');
+    }
+    pathFor(key) {
+        const path = normalize(join(this.blobRoot, key));
+        if (!path.startsWith(this.blobRoot + sep))
+            throw new Error('key escapes storage root');
+        return path;
+    }
+    async put(key, data, _opts) {
+        const finalPath = this.pathFor(key);
+        const tmpPath = join(this.tmpRoot, randomUUID());
+        await mkdir(this.tmpRoot, { recursive: true });
+        await mkdir(dirname(finalPath), { recursive: true });
+        try {
+            await pipeline(data, createWriteStream(tmpPath, { flags: 'wx' }));
+            await rename(tmpPath, finalPath);
+        }
+        catch (err) {
+            await rm(tmpPath, { force: true });
+            throw err;
+        }
+    }
+    async getStream(key, range) {
+        const path = this.pathFor(key);
+        // Open eagerly: a missing blob must reject HERE, at the await — before
+        // the caller commits response headers — not as a late 'error' event on a
+        // lazily-opening createReadStream after a 200 is already on the wire
+        // (the s3 driver's GetObject await fails eagerly too; this matches it).
+        const handle = await open(path, 'r');
+        // autoClose (default) hands fd ownership to the stream: closed on end,
+        // error, and destroy — including the route's client-abort destroy().
+        return handle.createReadStream(range ? { start: range.start, end: range.end } : {});
+    }
+    async exists(key) {
+        return (await this.head(key)) !== null;
+    }
+    async head(key) {
+        try {
+            const s = await stat(this.pathFor(key));
+            return { sizeBytes: s.size };
+        }
+        catch (err) {
+            // A missing file is `null`; any other stat error (permissions, I/O)
+            // propagates rather than masquerading as "absent".
+            if (isEnoent(err))
+                return null;
+            throw err;
+        }
+    }
+    async delete(key) {
+        // Deleting an already-gone blob is a no-op; real errors propagate and the
+        // caller decides whether they are fatal.
+        try {
+            await unlink(this.pathFor(key));
+        }
+        catch (err) {
+            if (!isEnoent(err))
+                throw err;
+        }
+    }
+    async healthcheck() {
+        await mkdir(this.tmpRoot, { recursive: true });
+        const probe = join(this.tmpRoot, `.healthcheck-${randomUUID()}`);
+        await writeFile(probe, 'ok');
+        await unlink(probe);
+    }
+}
+//# sourceMappingURL=local.js.map

package/dist/storage/local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.js","sourceRoot":"","sources":["../../src/storage/local.ts"],"names":[],"mappings":"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"}

package/dist/storage/s3.d.ts

@@ -0,0 +1,29 @@
+import type { Readable } from 'node:stream';
+import type { ByteRange, HeadResult, PutOptions, StorageDriver } from './driver.js';
+export interface S3DriverConfig {
+    bucket: string;
+    region: string;
+    endpoint?: string | undefined;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Required for MinIO and most S3-compatibles. */
+    forcePathStyle: boolean;
+}
+/**
+ * S3-compatible driver: MinIO self-hosted, AWS S3, Cloudflare R2 (and any
+ * endpoint speaking the S3 API). Multi-replica safe — this is the Profile B
+ * storage driver.
+ */
+export declare class S3StorageDriver implements StorageDriver {
+    readonly name: "s3";
+    private readonly client;
+    private readonly bucket;
+    constructor(config: S3DriverConfig);
+    put(key: string, data: Readable, opts: PutOptions): Promise<void>;
+    getStream(key: string, range?: ByteRange): Promise<Readable>;
+    exists(key: string): Promise<boolean>;
+    head(key: string): Promise<HeadResult | null>;
+    delete(key: string): Promise<void>;
+    healthcheck(): Promise<void>;
+}
+//# sourceMappingURL=s3.d.ts.map

package/dist/storage/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/storage/s3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAU5C,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAQpF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,eAAgB,YAAW,aAAa;IACnD,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAU;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,cAAc;IAa5B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAejE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IAY5D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAa7C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAOnC"}

package/dist/storage/s3.js

@@ -0,0 +1,82 @@
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { Upload } from '@aws-sdk/lib-storage';
+import { randomUUID } from 'node:crypto';
+/** A missing object — the only S3 error head()/exists() treats as "absent". */
+function isNotFound(err) {
+    const e = err;
+    return e?.name === 'NotFound' || e?.name === 'NoSuchKey' || e?.$metadata?.httpStatusCode === 404;
+}
+/**
+ * S3-compatible driver: MinIO self-hosted, AWS S3, Cloudflare R2 (and any
+ * endpoint speaking the S3 API). Multi-replica safe — this is the Profile B
+ * storage driver.
+ */
+export class S3StorageDriver {
+    name = 's3';
+    client;
+    bucket;
+    constructor(config) {
+        this.bucket = config.bucket;
+        this.client = new S3Client({
+            region: config.region,
+            ...(config.endpoint ? { endpoint: config.endpoint } : {}),
+            forcePathStyle: config.forcePathStyle,
+            credentials: {
+                accessKeyId: config.accessKeyId,
+                secretAccessKey: config.secretAccessKey
+            }
+        });
+    }
+    async put(key, data, opts) {
+        // lib-storage handles multipart for large bodies and backpressure.
+        const upload = new Upload({
+            client: this.client,
+            params: {
+                Bucket: this.bucket,
+                Key: key,
+                Body: data,
+                ContentType: opts.contentType,
+                ContentLength: opts.sizeBytes
+            }
+        });
+        await upload.done();
+    }
+    async getStream(key, range) {
+        const res = await this.client.send(new GetObjectCommand({
+            Bucket: this.bucket,
+            Key: key,
+            ...(range ? { Range: `bytes=${range.start}-${range.end}` } : {})
+        }));
+        if (!res.Body)
+            throw new Error('empty S3 response body');
+        return res.Body;
+    }
+    async exists(key) {
+        return (await this.head(key)) !== null;
+    }
+    async head(key) {
+        try {
+            const res = await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: key }));
+            return { sizeBytes: res.ContentLength ?? 0 };
+        }
+        catch (err) {
+            // Only a genuine miss is `null`. A transport/permission error must
+            // propagate — swallowing it made a broken bucket look like an empty one,
+            // and exists() (upload dedup) would then re-put or 400 misleadingly.
+            if (isNotFound(err))
+                return null;
+            throw err;
+        }
+    }
+    async delete(key) {
+        // S3 DeleteObject is idempotent (no error on a missing key); a real
+        // failure propagates and the caller decides whether it is fatal.
+        await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
+    }
+    async healthcheck() {
+        const probe = `.healthcheck/${randomUUID()}`;
+        await this.client.send(new PutObjectCommand({ Bucket: this.bucket, Key: probe, Body: 'ok', ContentLength: 2 }));
+        await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: probe }));
+    }
+}
+//# sourceMappingURL=s3.js.map

package/dist/storage/s3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.js","sourceRoot":"","sources":["../../src/storage/s3.ts"],"names":[],"mappings":"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"}