@ariestools/aries-dapp-core 0.1.7 → 0.1.8

package/dist/bin/dappServer.mjs

@@ -2,16 +2,18 @@
 import { readFileSync } from "node:fs";
 import { DAPP_BACKINGS, DAPP_BUCKETS, isDappBackingKind, resolveBacking, startDappServer } from "@ariestools/aries-dapp-serve";
 import { AbstractCreatable, ConsoleLogger, IdLogger, assertEx, creatable } from "@ariestools/sdk";
-import { GetObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
 //#region src/actor/AbstractActor.ts
-function createDeferred() {
+function createDeferred$1() {
 	let resolve;
 	let reject;
+	const promise = new Promise((res, rej) => {
+		resolve = res;
+		reject = rej;
+	});
+	promise.catch(() => {});
 	return {
-		promise: new Promise((res, rej) => {
-			resolve = res;
-			reject = rej;
-		}),
+		promise,
 		reject,
 		resolve
 	};
@@ -32,9 +34,10 @@ function createDeferred() {
 var AbstractActor = class extends AbstractCreatable {
 	_intervals = /* @__PURE__ */ new Map();
 	_timeouts = /* @__PURE__ */ new Map();
+	_abortController = new AbortController();
 	_idLogger;
 	_inFlight = /* @__PURE__ */ new Map();
-	_readyDeferred = createDeferred();
+	_readyDeferred = createDeferred$1();
 	_readyError;
 	_readyState = "pending";
 	get logger() {
@@ -53,6 +56,10 @@ var AbstractActor = class extends AbstractCreatable {
 	get locator() {
 		return this.params.locator;
 	}
+	/** Abort signal cancelled when the actor stops (or is replaced on restart). */
+	get signal() {
+		return this._abortController.signal;
+	}
 	static async paramsHandler(params) {
 		const inParams = params ?? {};
 		const baseParams = await super.paramsHandler({
@@ -65,11 +72,14 @@ var AbstractActor = class extends AbstractCreatable {
 			locator
 		};
 	}
+	/** Override to prove the actor can do useful work. Default: no-op. */
+	async readyHandler() {}
 	/**
-	* Register a recurring task. The interval only fires while the actor is
-	* `started`, and a run is skipped if the previous one is still in flight, so
-	* a slow pass can never stack on top of itself. Must be called from
-	* `startHandler` (guards on `starting` status), mirroring the xl1 actor.
+	* Register a recurring task. The first invocation fires after `dueTimeMs`
+	* (the documented first-run delay); subsequent invocations fire every
+	* `periodMs` while the actor is `started`. A run is skipped if the previous
+	* one is still in flight, so a slow pass can never stack on top of itself.
+	* Must be called from `startHandler` (guards on `starting` status).
 	*/
 	registerTimer(timerName, callback, dueTimeMs, periodMs) {
 		if (this.status !== "starting") {
@@ -77,7 +87,7 @@ var AbstractActor = class extends AbstractCreatable {
 			return;
 		}
 		const tick = () => {
-			if (this.status !== "started" || !this._intervals.has(timerName)) return;
+			if (this.status !== "started") return;
 			if (this._inFlight.has(timerName)) {
 				this.logger.warn(`Skipping timer '${this.name}:${timerName}' because the previous run is still in flight.`);
 				return;
@@ -99,13 +109,15 @@ var AbstractActor = class extends AbstractCreatable {
 			}));
 		};
 		const timeoutId = setTimeout(() => {
+			if (this.status !== "started") return;
 			this._intervals.set(timerName, setInterval(tick, periodMs));
+			tick();
 		}, dueTimeMs);
 		this._timeouts.set(timerName, timeoutId);
 	}
 	/**
-	* Run the warm-pass once. Not driven automatically here (no orchestrator);
-	* a caller invokes it after `start()` if it wants `whenReady()` to resolve.
+	* Run the warm-pass once. The standard boot path invokes this after
+	* `start()` so readiness either resolves or rejects.
 	*/
 	async runReadyHandler() {
 		if (this._readyState !== "pending") return;
@@ -121,22 +133,81 @@ var AbstractActor = class extends AbstractCreatable {
 			throw err;
 		}
 	}
+	async startHandler() {
+		if (this._abortController.signal.aborted) this._abortController = new AbortController();
+		await super.startHandler();
+	}
 	async stopHandler() {
 		await super.stopHandler();
+		this._abortController.abort();
 		for (const timeoutRef of this._timeouts.values()) clearTimeout(timeoutRef);
 		this._timeouts.clear();
 		for (const intervalRef of this._intervals.values()) clearInterval(intervalRef);
 		this._intervals.clear();
-		await Promise.allSettled(this._inFlight.values());
+		const inFlight = [...this._inFlight.values()];
 		this._inFlight.clear();
+		const timeoutMs = this.params.shutdownTimeoutMs;
+		if (timeoutMs === void 0) {
+			await Promise.allSettled(inFlight);
+			return;
+		}
+		await Promise.race([Promise.allSettled(inFlight), new Promise((resolve) => {
+			setTimeout(resolve, timeoutMs);
+		})]);
 	}
 	async whenReady() {
 		await this._readyDeferred.promise;
 	}
-	/** Override to prove the actor can do useful work. Default: no-op. */
-	async readyHandler() {}
 };
 //#endregion
+//#region src/providers/capabilities.ts
+/** Thrown when a read-only capability wrapper receives a write. */
+var ReadOnlyStoreError = class extends Error {
+	name = "ReadOnlyStoreError";
+	constructor(role, operation = "put") {
+		super(`Store role "${role}" is read-only; ${operation} is not permitted`);
+	}
+};
+function bindReader(store) {
+	return {
+		role: store.role,
+		bucket: store.bucket,
+		prefix: store.prefix,
+		...store.publicBaseUrl !== void 0 && { publicBaseUrl: store.publicBaseUrl },
+		destroy: () => store.destroy(),
+		get: (key) => store.get(key),
+		getWithMeta: (key) => store.getWithMeta(key),
+		list: (listPrefix) => store.list(listPrefix),
+		listAsync: (listPrefix) => store.listAsync(listPrefix),
+		listPage: (options) => store.listPage(options),
+		publicUrl: (key) => store.publicUrl(key),
+		resolveKey: (key) => store.resolveKey(key),
+		stat: (key) => store.stat(key)
+	};
+}
+/**
+* Wrap any writer as a read-only reader. Other methods and destroy delegate to
+* the underlying store.
+*/
+function asReadOnly(store) {
+	return bindReader(store);
+}
+/**
+* Wrap a writer so `put` fails even if the caller still holds the writer type
+* (defense in depth for the data-role locator registration).
+*/
+function asReadOnlyWriter(store) {
+	return {
+		...bindReader(store),
+		async put() {
+			throw new ReadOnlyStoreError(store.role, "put");
+		},
+		async delete() {
+			throw new ReadOnlyStoreError(store.role, "delete");
+		}
+	};
+}
+//#endregion
 //#region src/providers/monikers.ts
 /**
 * Provider monikers for the three dapp buckets. An actor declares these in its
@@ -146,6 +217,108 @@ const DappDataStoreMoniker = "DappDataStore";
 const DappStateStoreMoniker = "DappStateStore";
 const DappIndexStoreMoniker = "DappIndexStore";
 //#endregion
+//#region src/publication/constants.ts
+/** Well-known relative keys published by the coherent generation protocol. */
+const HEAD_KEY = "head.json";
+const STATUS_KEY = "status.json";
+/** CDN caching: mutable head and status objects that must revalidate. */
+const CACHE_CONTROL_REVALIDATE = "public, max-age=0, must-revalidate";
+const INDEXER_STATUS_SCHEMA = "network.aries.dapp.indexer.status";
+//#endregion
+//#region src/publication/status.ts
+function encodeStatus(status) {
+	return `${JSON.stringify(status, null, 2)}\n`;
+}
+/**
+* Read the durable indexer status object from a state (or status) store.
+* Returns undefined when no status has been published yet.
+*/
+async function readIndexerStatus(store, key = STATUS_KEY) {
+	const body = await store.get(key);
+	if (body === void 0) return void 0;
+	const parsed = JSON.parse(new TextDecoder().decode(body));
+	if (parsed === null || typeof parsed !== "object") throw new Error(`Invalid indexer status at "${key}": not an object`);
+	const record = parsed;
+	if (record.schema !== "network.aries.dapp.indexer.status") throw new Error(`Invalid indexer status schema at "${key}": ${String(record.schema)}`);
+	return record;
+}
+/**
+* Publish a machine-readable status object with revalidate CDN caching.
+* Status never carries credentials or private application material.
+*/
+async function writeIndexerStatus(store, input) {
+	const key = input.key ?? "status.json";
+	const status = {
+		schema: INDEXER_STATUS_SCHEMA,
+		consecutiveFailures: input.consecutiveFailures,
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		...input.floor !== void 0 && { floor: input.floor },
+		...input.cursor !== void 0 && { cursor: input.cursor },
+		...input.lastCompletedPosition !== void 0 && { lastCompletedPosition: input.lastCompletedPosition },
+		...input.observedSourceHead !== void 0 && { observedSourceHead: input.observedSourceHead },
+		...input.generation !== void 0 && { generation: input.generation },
+		...input.generationRoot !== void 0 && { generationRoot: input.generationRoot },
+		...input.lastSuccessAt !== void 0 && { lastSuccessAt: input.lastSuccessAt },
+		...input.lastErrorAt !== void 0 && { lastErrorAt: input.lastErrorAt },
+		...input.lastError !== void 0 && { lastError: input.lastError }
+	};
+	await store.put(key, encodeStatus(status), {
+		contentType: "application/json",
+		cacheControl: CACHE_CONTROL_REVALIDATE
+	});
+	return status;
+}
+//#endregion
+//#region src/publication/statusPatch.ts
+function pickDefined(source, keys) {
+	const out = {};
+	for (const key of keys) {
+		const value = source[key];
+		if (value !== void 0) out[key] = value;
+	}
+	return out;
+}
+const PROGRESS_KEYS = [
+	"floor",
+	"cursor",
+	"lastCompletedPosition",
+	"observedSourceHead",
+	"generation",
+	"generationRoot"
+];
+/** Carry forward durable progress fields from a prior status object. */
+function priorProgressFields(prior) {
+	if (prior === void 0) return {};
+	return {
+		...pickDefined(prior, PROGRESS_KEYS),
+		...prior.lastSuccessAt !== void 0 && { lastSuccessAt: prior.lastSuccessAt }
+	};
+}
+/** Build success status fields from reduce progress, falling back to prior. */
+function successStatusFields(progress, prior, now) {
+	const fromProgress = progress === void 0 ? {} : pickDefined(progress, PROGRESS_KEYS);
+	const generation = progress?.generation ?? prior?.generation;
+	const generationRoot = progress?.generationRoot ?? prior?.generationRoot;
+	return {
+		consecutiveFailures: 0,
+		...fromProgress,
+		...generation !== void 0 && { generation },
+		...generationRoot !== void 0 && { generationRoot },
+		lastSuccessAt: now,
+		...prior?.lastError !== void 0 && { lastError: prior.lastError },
+		...prior?.lastErrorAt !== void 0 && { lastErrorAt: prior.lastErrorAt }
+	};
+}
+/** Build failure status fields while preserving prior checkpoint progress. */
+function failureStatusFields(prior, consecutiveFailures, error, now) {
+	return {
+		consecutiveFailures,
+		...priorProgressFields(prior),
+		lastError: error.message,
+		lastErrorAt: now
+	};
+}
+//#endregion
 //#region \0@oxc-project+runtime@0.140.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -157,6 +330,29 @@ function __decorate(decorators, target, key, desc) {
 //#region src/DappActor.ts
 const DEFAULT_REDUCE_INTERVAL_MS = 5e3;
 const DEFAULT_FIRST_RUN_DELAY_MS = 2e3;
+const REDUCE_TIMER = "DappReduce";
+function createDeferred() {
+	let resolve;
+	let reject;
+	const promise = new Promise((res, rej) => {
+		resolve = res;
+		reject = rej;
+	});
+	promise.catch(() => {});
+	return {
+		promise,
+		reject,
+		resolve
+	};
+}
+function withDefaultGenerationRoot(result) {
+	if (result === void 0) return;
+	if (result.generation === void 0 || result.generationRoot !== void 0) return result;
+	return {
+		...result,
+		generationRoot: HEAD_KEY
+	};
+}
 let DappActor = class DappActor extends AbstractActor {
 	static dependencies = [
 		DappDataStoreMoniker,
@@ -166,28 +362,88 @@ let DappActor = class DappActor extends AbstractActor {
 	_data;
 	_index;
 	_state;
+	_consecutiveFailures = 0;
+	_firstPass = createDeferred();
+	_firstPassSettled = false;
+	/** Consecutive reduce failures since the last success. */
+	get consecutiveFailures() {
+		return this._consecutiveFailures;
+	}
 	async createHandler() {
 		await super.createHandler();
-		this._data = await this.locator.getInstance(DappDataStoreMoniker);
+		const dataWriter = await this.locator.getInstance(DappDataStoreMoniker);
+		this._data = asReadOnly(dataWriter);
 		this._state = await this.locator.getInstance(DappStateStoreMoniker);
 		this._index = await this.locator.getInstance(DappIndexStoreMoniker);
 	}
+	async readyHandler() {
+		await this._firstPass.promise;
+	}
 	async startHandler() {
 		await super.startHandler();
 		const interval = this.params.reduceIntervalMs ?? DEFAULT_REDUCE_INTERVAL_MS;
 		const firstRunDelay = this.params.firstRunDelayMs ?? DEFAULT_FIRST_RUN_DELAY_MS;
-		this.registerTimer("DappReduce", async () => {
+		this.registerTimer(REDUCE_TIMER, async () => {
 			await this.runReducePass();
 		}, firstRunDelay, interval);
-		this.logger.info(`DappActor started: reducer '${this.params.reducer.name}' every ${interval}ms`);
+		this.logger.info(`DappActor started: reducer '${this.params.reducer.name}' every ${interval}ms (first run in ${firstRunDelay}ms)`);
+	}
+	async stopHandler() {
+		this.settleFirstPass(/* @__PURE__ */ new Error("Actor stopped before first reduce pass completed"));
+		await super.stopHandler();
+	}
+	async publishStatusFromProgress(progress, error) {
+		if (this.params.publishStatus === false) return;
+		let prior;
+		try {
+			prior = await readIndexerStatus(this._state);
+		} catch {
+			prior = void 0;
+		}
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const fields = error === void 0 ? successStatusFields(progress, prior, now) : failureStatusFields(prior, this._consecutiveFailures, error, now);
+		await writeIndexerStatus(this._state, fields);
 	}
 	async runReducePass() {
-		await this.params.reducer.reduce({
-			data: this._data,
-			index: this._index,
-			logger: this.logger,
-			state: this._state
-		});
+		try {
+			const result = await this.params.reducer.reduce({
+				data: this._data,
+				index: this._index,
+				logger: this.logger,
+				signal: this.signal,
+				state: this._state
+			});
+			const progress = withDefaultGenerationRoot(result === void 0 ? void 0 : result);
+			this._consecutiveFailures = 0;
+			await this.safePublishStatus(progress);
+			this.settleFirstPass();
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
+			this._consecutiveFailures += 1;
+			await this.safePublishStatus(void 0, err);
+			this.settleFirstPass(err);
+			this.logger.error(`Error in reduce pass for '${this.params.reducer.name}': ${err.message}`);
+			const max = this.params.maxConsecutiveFailures;
+			if (max !== void 0 && this._consecutiveFailures >= max) {
+				this.logger.error(`Reducer '${this.params.reducer.name}' failed ${this._consecutiveFailures} consecutive times; stopping actor`);
+				setTimeout(() => {
+					this.stop();
+				}, 0);
+			}
+		}
+	}
+	async safePublishStatus(progress, error) {
+		try {
+			await this.publishStatusFromProgress(progress, error);
+		} catch (statusError) {
+			this.logger.error(`Failed to publish indexer status: ${String(statusError)}`);
+		}
+	}
+	settleFirstPass(error) {
+		if (this._firstPassSettled) return;
+		this._firstPassSettled = true;
+		if (error === void 0) this._firstPass.resolve();
+		else this._firstPass.reject(error);
 	}
 };
 DappActor = __decorate([creatable()], DappActor);
@@ -195,112 +451,356 @@ DappActor = __decorate([creatable()], DappActor);
 //#region src/boot/bootDappActors.ts
 /**
 * Creates and starts one {@link DappActor} per spec, all sharing the single
-* process-wide locator. Returns them so the caller can stop them on shutdown.
+* process-wide locator. On partial failure, actors already started are stopped
+* before the error is rethrown. Returns them so the caller can stop them on
+* shutdown.
 */
 async function bootDappActors(locator, specs) {
 	const actors = [];
-	for (const spec of specs) {
-		const params = {
-			locator,
-			name: spec.name,
-			reducer: spec.reducer,
-			...spec.reduceIntervalMs !== void 0 && { reduceIntervalMs: spec.reduceIntervalMs }
-		};
-		const actor = await DappActor.create(params);
-		await actor.start();
-		actors.push(actor);
+	try {
+		for (const spec of specs) {
+			const params = {
+				locator,
+				name: spec.name,
+				reducer: spec.reducer,
+				...spec.reduceIntervalMs !== void 0 && { reduceIntervalMs: spec.reduceIntervalMs },
+				...spec.firstRunDelayMs !== void 0 && { firstRunDelayMs: spec.firstRunDelayMs },
+				...spec.maxConsecutiveFailures !== void 0 && { maxConsecutiveFailures: spec.maxConsecutiveFailures },
+				...spec.publishStatus !== void 0 && { publishStatus: spec.publishStatus },
+				...spec.shutdownTimeoutMs !== void 0 && { shutdownTimeoutMs: spec.shutdownTimeoutMs }
+			};
+			const actor = await DappActor.create(params);
+			await actor.start();
+			actors.push(actor);
+			if (spec.runReady !== false) await actor.runReadyHandler();
+		}
+		return actors;
+	} catch (error) {
+		for (const actor of [...actors].reverse()) try {
+			await actor.stop();
+		} catch {}
+		throw error;
+	}
+}
+//#endregion
+//#region src/providers/errors.ts
+/**
+* Thrown when a conditional put fails (object already exists under
+* `ifNotExists`, or ETag mismatch under `ifMatch`).
+*/
+var ConditionalWriteError = class extends Error {
+	key;
+	name = "ConditionalWriteError";
+	constructor(key, message) {
+		super(message ?? `Conditional write failed for key "${key}"`);
+		this.key = key;
 	}
-	return actors;
+};
+//#endregion
+//#region src/providers/joinKey.ts
+/**
+* Join a role prefix with a relative object key into a physical S3 key.
+* Empty prefix yields the relative key unchanged; empty relative yields the
+* prefix without a trailing slash.
+*/
+function joinKey(prefix, relativeKey) {
+	const cleanPrefix = prefix.replaceAll(/^\/+|\/+$/g, "");
+	const cleanKey = relativeKey.replaceAll(/^\/+/g, "");
+	if (cleanPrefix.length === 0) return cleanKey;
+	if (cleanKey.length === 0) return cleanPrefix;
+	return `${cleanPrefix}/${cleanKey}`;
+}
+/** Strip a role prefix from a physical key, returning the relative key. */
+function stripPrefix(prefix, physicalKey) {
+	const cleanPrefix = prefix.replaceAll(/^\/+|\/+$/g, "");
+	if (cleanPrefix.length === 0) return physicalKey;
+	const withSlash = `${cleanPrefix}/`;
+	if (physicalKey === cleanPrefix) return "";
+	if (physicalKey.startsWith(withSlash)) return physicalKey.slice(withSlash.length);
+	return physicalKey;
+}
+/** Normalize an optional public base URL (no trailing slash). */
+function normalizePublicBaseUrl(url) {
+	if (url === void 0 || url.length === 0) return void 0;
+	return url.replace(/\/+$/, "");
 }
 //#endregion
 //#region src/providers/DappBucketStore.ts
 const DEFAULT_CREDENTIAL = "S3RVER";
+const DEFAULT_REGION = "us-east-1";
 function isNotFound(error) {
 	const name = error.name;
-	return name === "NoSuchKey" || name === "NotFound";
+	const status = error.$metadata?.httpStatusCode;
+	return name === "NoSuchKey" || name === "NotFound" || name === "404" || status === 404;
+}
+function isConditionalFailure(error) {
+	const name = error.name;
+	const status = error.$metadata?.httpStatusCode;
+	return name === "PreconditionFailed" || name === "ConditionalRequestConflict" || name === "412" || status === 412;
+}
+function toBodyBytes(body) {
+	return typeof body === "string" ? new TextEncoder().encode(body) : body;
+}
+function metaFromResponse(response) {
+	return {
+		...response.CacheControl !== void 0 && { cacheControl: response.CacheControl },
+		...response.ContentEncoding !== void 0 && { contentEncoding: response.ContentEncoding },
+		...response.ContentLength !== void 0 && { contentLength: response.ContentLength },
+		...response.ContentType !== void 0 && { contentType: response.ContentType },
+		...response.ETag !== void 0 && { etag: response.ETag },
+		...response.LastModified !== void 0 && { lastModified: response.LastModified },
+		...response.Metadata !== void 0 && Object.keys(response.Metadata).length > 0 && { metadata: response.Metadata }
+	};
+}
+/**
+* Resolve a shared S3 client from an injected instance or construct options.
+* Callers that build three role stores should resolve once and pass the same
+* client to each so dapp-core does not own one client per role.
+*/
+function resolveClientCredentials(options) {
+	if (options.credentials !== void 0) return options.credentials;
+	if (options.endpoint === void 0) return void 0;
+	return {
+		accessKeyId: DEFAULT_CREDENTIAL,
+		secretAccessKey: DEFAULT_CREDENTIAL
+	};
+}
+function resolveS3Client(options) {
+	if (options.client !== void 0) return {
+		client: options.client,
+		ownClient: options.ownClient ?? false
+	};
+	const credentials = resolveClientCredentials(options);
+	return {
+		client: new S3Client({
+			...options.endpoint !== void 0 && { endpoint: options.endpoint },
+			region: options.region ?? DEFAULT_REGION,
+			forcePathStyle: options.forcePathStyle ?? options.endpoint !== void 0,
+			...credentials !== void 0 && { credentials }
+		}),
+		ownClient: options.ownClient ?? true
+	};
 }
 /**
-* S3-backed {@link DappBucketStore} pointed at the local dapp server. Uses
-* path-style addressing so `/{bucket}/{key}` resolves as a subfolder of the
-* one origin. Under `--ssl auto` the server speaks HTTPS with a locally
-* trusted certificate; the daemon exports its CA via `NODE_EXTRA_CA_CERTS`, so
-* this client trusts it without any per-request handler configuration.
+* S3-backed {@link DappBucketStore}. Accepts an injected client (production)
+* or builds one from endpoint/credentials (local s3rver / simple configs).
+* Path-style addressing is the default when an endpoint is provided so local
+* fixtures and many R2 setups work without virtual-host DNS.
 */
 function createS3BucketStore(options) {
-	const { bucket } = options;
-	const client = new S3Client({
-		endpoint: options.endpoint,
-		region: "us-east-1",
-		forcePathStyle: true,
-		credentials: {
-			accessKeyId: options.accessKeyId ?? DEFAULT_CREDENTIAL,
-			secretAccessKey: options.secretAccessKey ?? DEFAULT_CREDENTIAL
-		}
-	});
+	const { role } = options;
+	const bindingPrefix = (options.binding.prefix ?? "").replaceAll(/^\/+|\/+$/g, "");
+	const publicBaseUrl = normalizePublicBaseUrl(options.binding.publicBaseUrl);
+	const { client, ownClient } = resolveS3Client(options);
+	const bucket = options.binding.bucket;
+	let destroyed = false;
+	function resolve(relativeKey) {
+		return joinKey(bindingPrefix, relativeKey);
+	}
 	return {
+		role,
 		bucket,
+		prefix: bindingPrefix,
+		...publicBaseUrl !== void 0 && { publicBaseUrl },
+		resolveKey(key) {
+			return resolve(key);
+		},
+		publicUrl(key) {
+			if (publicBaseUrl === void 0) return void 0;
+			const relative = key.replaceAll(/^\/+/g, "");
+			return relative.length === 0 ? publicBaseUrl : `${publicBaseUrl}/${relative}`;
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			if (ownClient) client.destroy();
+		},
 		async get(key) {
+			return (await this.getWithMeta(key))?.body;
+		},
+		async getWithMeta(key) {
+			try {
+				const response = await client.send(new GetObjectCommand({
+					Bucket: bucket,
+					Key: resolve(key)
+				}));
+				const body = await response.Body?.transformToByteArray();
+				if (body === void 0) return void 0;
+				return {
+					body,
+					meta: metaFromResponse(response)
+				};
+			} catch (error) {
+				if (isNotFound(error)) return void 0;
+				throw error;
+			}
+		},
+		async stat(key) {
 			try {
-				return await (await client.send(new GetObjectCommand({
+				return metaFromResponse(await client.send(new HeadObjectCommand({
 					Bucket: bucket,
-					Key: key
-				}))).Body?.transformToByteArray();
+					Key: resolve(key)
+				})));
 			} catch (error) {
 				if (isNotFound(error)) return void 0;
 				throw error;
 			}
 		},
-		async put(key, body) {
-			await client.send(new PutObjectCommand({
+		async put(key, body, putOptions) {
+			const physicalKey = resolve(key);
+			try {
+				const response = await client.send(new PutObjectCommand({
+					Bucket: bucket,
+					Key: physicalKey,
+					Body: toBodyBytes(body),
+					...putOptions?.contentType !== void 0 && { ContentType: putOptions.contentType },
+					...putOptions?.contentEncoding !== void 0 && { ContentEncoding: putOptions.contentEncoding },
+					...putOptions?.cacheControl !== void 0 && { CacheControl: putOptions.cacheControl },
+					...putOptions?.metadata !== void 0 && { Metadata: putOptions.metadata },
+					...putOptions?.ifNotExists === true && { IfNoneMatch: "*" },
+					...putOptions?.ifMatch !== void 0 && { IfMatch: putOptions.ifMatch }
+				}));
+				return { ...response.ETag !== void 0 && { etag: response.ETag } };
+			} catch (error) {
+				if (isConditionalFailure(error)) throw new ConditionalWriteError(key);
+				throw error;
+			}
+		},
+		async delete(key) {
+			await client.send(new DeleteObjectCommand({
 				Bucket: bucket,
-				Key: key,
-				Body: body
+				Key: resolve(key)
 			}));
 		},
 		async list(prefix) {
 			const keys = [];
+			for await (const key of this.listAsync(prefix)) keys.push(key);
+			return keys;
+		},
+		async listPage(pageOptions = {}) {
+			const physicalPrefix = pageOptions.prefix === void 0 ? bindingPrefix.length === 0 ? void 0 : `${bindingPrefix}/` : resolve(pageOptions.prefix);
+			const response = await client.send(new ListObjectsV2Command({
+				Bucket: bucket,
+				...physicalPrefix !== void 0 && { Prefix: physicalPrefix },
+				...pageOptions.continuationToken !== void 0 && { ContinuationToken: pageOptions.continuationToken },
+				...pageOptions.maxKeys !== void 0 && { MaxKeys: pageOptions.maxKeys }
+			}));
+			const keys = [];
+			for (const item of response.Contents ?? []) {
+				if (item.Key === void 0) continue;
+				keys.push(stripPrefix(bindingPrefix, item.Key));
+			}
+			const isTruncated = response.IsTruncated === true;
+			return {
+				keys,
+				isTruncated,
+				...isTruncated && response.NextContinuationToken !== void 0 && { continuationToken: response.NextContinuationToken }
+			};
+		},
+		async *listAsync(prefix) {
 			let token;
 			do {
-				const response = await client.send(new ListObjectsV2Command({
-					Bucket: bucket,
-					Prefix: prefix,
-					ContinuationToken: token
-				}));
-				for (const item of response.Contents ?? []) if (item.Key !== void 0) keys.push(item.Key);
-				token = response.IsTruncated === true ? response.NextContinuationToken : void 0;
+				const page = await this.listPage({
+					...prefix !== void 0 && { prefix },
+					...token !== void 0 && { continuationToken: token }
+				});
+				for (const key of page.keys) yield key;
+				token = page.continuationToken;
 			} while (token !== void 0);
-			return keys;
 		}
 	};
 }
 //#endregion
 //#region src/locator/createDappLocator.ts
+const DEFAULT_BINDINGS = {
+	data: { bucket: "data" },
+	state: { bucket: "state" },
+	index: { bucket: "index" }
+};
+const ROLE_MONIKERS = {
+	data: DappDataStoreMoniker,
+	state: DappStateStoreMoniker,
+	index: DappIndexStoreMoniker
+};
+function resolveCredentials(options) {
+	if (options.credentials !== void 0) return options.credentials;
+	if (options.accessKeyId !== void 0 || options.secretAccessKey !== void 0) return {
+		accessKeyId: options.accessKeyId ?? "S3RVER",
+		secretAccessKey: options.secretAccessKey ?? "S3RVER"
+	};
+}
+function resolveSharedClient(options) {
+	const credentials = resolveCredentials(options);
+	if (options.client !== void 0) return {
+		client: options.client,
+		ownClient: options.ownClient ?? false
+	};
+	return resolveS3Client({
+		...options.endpoint !== void 0 && { endpoint: options.endpoint },
+		...options.region !== void 0 && { region: options.region },
+		...options.forcePathStyle !== void 0 && { forcePathStyle: options.forcePathStyle },
+		...credentials !== void 0 && { credentials },
+		ownClient: options.ownClient
+	});
+}
+function resolveRoleClient(role, options, shared) {
+	const override = options.clients?.[role];
+	if (override === void 0) return shared;
+	if (typeof override.send === "function") return {
+		client: override,
+		ownClient: false
+	};
+	return resolveS3Client({
+		...override,
+		ownClient: override.ownClient ?? true
+	});
+}
 /**
 * Builds the process-wide locator: one instance, shared across every actor
-* (xl1-cli style). It pre-registers an S3-backed store per bucket keyed by
-* moniker; extra providers can be `register`ed before actors are created.
+* (xl1-cli style). It pre-registers an S3-backed store per logical role using
+* either the default local bucket names or explicit production bindings.
+* Extra providers can be `register`ed before actors are created.
+*
+* Prefer a shared {@link client} when all roles share one principal; use
+* {@link CreateDappLocatorOptions.clients} for distinct least-privilege
+* credentials per role. Call `destroy()` on shutdown when the locator owns
+* any client it constructed.
 */
 function createDappLocator(options) {
 	const logger = options.logger ?? new ConsoleLogger();
-	const bucketOptions = {
-		endpoint: options.endpoint,
-		...options.accessKeyId !== void 0 && { accessKeyId: options.accessKeyId },
-		...options.secretAccessKey !== void 0 && { secretAccessKey: options.secretAccessKey }
+	const bindings = options.bindings ?? DEFAULT_BINDINGS;
+	const shared = resolveSharedClient(options);
+	const readOnlyData = options.readOnlyData !== false;
+	const roles = [
+		"data",
+		"state",
+		"index"
+	];
+	const instances = /* @__PURE__ */ new Map();
+	const stores = [];
+	const ownedClients = [];
+	const seenClients = /* @__PURE__ */ new Set();
+	const trackClient = (owned) => {
+		if (!owned.ownClient || seenClients.has(owned.client)) return;
+		seenClients.add(owned.client);
+		ownedClients.push(owned);
 	};
-	const instances = /* @__PURE__ */ new Map([
-		[DappDataStoreMoniker, createS3BucketStore({
-			...bucketOptions,
-			bucket: "data"
-		})],
-		[DappStateStoreMoniker, createS3BucketStore({
-			...bucketOptions,
-			bucket: "state"
-		})],
-		[DappIndexStoreMoniker, createS3BucketStore({
-			...bucketOptions,
-			bucket: "index"
-		})]
-	]);
+	trackClient(shared);
+	for (const role of roles) {
+		const binding = bindings[role];
+		const roleClient = resolveRoleClient(role, options, shared);
+		trackClient(roleClient);
+		let store = createS3BucketStore({
+			role,
+			binding,
+			client: roleClient.client,
+			ownClient: false
+		});
+		if (role === "data" && readOnlyData) store = asReadOnlyWriter(store);
+		stores.push(store);
+		instances.set(ROLE_MONIKERS[role], store);
+	}
+	let destroyed = false;
 	return {
 		context: { logger },
 		has(moniker) {
@@ -316,15 +816,21 @@ function createDappLocator(options) {
 		},
 		async tryGetInstance(moniker) {
 			return instances.get(moniker);
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			for (const store of stores) store.destroy();
+			for (const owned of ownedClients) if (owned.ownClient) owned.client.destroy();
 		}
 	};
 }
 //#endregion
 //#region src/reducer/DappReducer.ts
 /**
-* Default reducer: does nothing. The harness runs the full timer/provider
-* spine with this in place; supply a real reducer to derive `state` and
-* `index` from `data`.
+* Default reducer: does nothing. The local harness runs the full timer/provider
+* spine with this in place; production entrypoints must supply a real reducer.
+* **Development only** — not a production indexer.
 */
 const noopReducer = {
 	name: "noop",
@@ -333,10 +839,14 @@ const noopReducer = {
 //#endregion
 //#region src/bin/dappServer.ts
 /**
-* Composed dapp daemon: boots the S3-compatible storage server (from
-* `@ariestools/aries-dapp-serve`) and, in the same process, a shared
-* process-wide locator plus the DappActor(s) that derive `state`/`index` from
-* `data` on an interval. Spawned by `aries dapp up`.
+* **Local development only.** Composed dapp daemon: boots the embedded
+* S3-compatible storage server (from `@ariestools/aries-dapp-serve`) and, in
+* the same process, a shared process-wide locator plus a `noopReducer`
+* DappActor. Spawned by `aries dapp up`.
+*
+* Production indexers must not use this binary. Compose `dapp-core` from a
+* project-owned entrypoint with real store bindings, an injected S3/R2 client,
+* and a real reducer — see the package README.
 */
 const PORT = Number(process.env.DAPP_PORT ?? 8801);
 const HOST = process.env.HOST ?? "127.0.0.1";
@@ -360,17 +870,21 @@ async function main() {
 		}
 	});
 	const logger = new ConsoleLogger();
-	const actors = await bootDappActors(createDappLocator({
+	const locator = createDappLocator({
 		endpoint: server.baseUrl,
 		logger
-	}), [{
+	});
+	const actors = await bootDappActors(locator, [{
 		name: "DappActor",
 		reducer: noopReducer,
-		reduceIntervalMs: REDUCE_INTERVAL_MS
+		reduceIntervalMs: REDUCE_INTERVAL_MS,
+		firstRunDelayMs: 0,
+		publishStatus: false
 	}]);
-	console.log(`dapp server listening at ${server.baseUrl}\n` + DAPP_BUCKETS.map((bucket) => `  /${bucket.padEnd(5)} ${server.baseUrl}/${bucket}`).join("\n") + `\nbacking: ${backing.description} — ${backing.directory}\nactors: ${actors.length} (reducer '${noopReducer.name}', every ${REDUCE_INTERVAL_MS}ms)`);
+	console.log(`[dev-only] dapp server listening at ${server.baseUrl}\n` + DAPP_BUCKETS.map((bucket) => `  /${bucket.padEnd(5)} ${server.baseUrl}/${bucket}`).join("\n") + `\nbacking: ${backing.description} — ${backing.directory}\nactors: ${actors.length} (reducer '${noopReducer.name}', every ${REDUCE_INTERVAL_MS}ms)`);
 	const shutdown = async () => {
 		for (const actor of actors) await actor.stop();
+		locator.destroy();
 		await server.close();
 		process.exit(0);
 	};