@ariestools/cli 0.1.8 → 0.1.10

package/dist/bin/daemons/dapp-server.mjs

@@ -0,0 +1,970 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { DAPP_BACKINGS, DAPP_BUCKETS, isDappBackingKind, resolveBacking, startDappServer } from "@ariestools/aries-dapp-serve";
+import { AbstractCreatable, ConsoleLogger, IdLogger, assertEx, creatable } from "@ariestools/sdk";
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { pathToFileURL } from "node:url";
+//#region src/actor/AbstractActor.ts
+function createDeferred$1() {
+	let resolve;
+	let reject;
+	const promise = new Promise((res, rej) => {
+		resolve = res;
+		reject = rej;
+	});
+	promise.catch(() => {});
+	return {
+		promise,
+		reject,
+		resolve
+	};
+}
+/**
+* Lean, dapp-owned fork of the xl1 `ActorV3` pattern: the create/start/stop
+* lifecycle from `AbstractCreatable`, plus non-overlapping interval timers and
+* a readiness contract. It deliberately swaps the chain's
+* `ProviderFactoryLocator`/`LocatorConfig` machinery for the small
+* {@link DappProviderLocator} seam, so a dapp actor resolves providers by
+* moniker without dragging the chain protocol config model in.
+*
+* The locator is process-wide: the daemon builds it once and passes the same
+* instance to every actor via `params.locator` (see `bootDappActors`). When
+* this graduates into a shared cli/actor toolkit — and, later, xl1-protocol —
+* this base can re-adopt the real locator.
+*/
+var AbstractActor = class extends AbstractCreatable {
+	_intervals = /* @__PURE__ */ new Map();
+	_timeouts = /* @__PURE__ */ new Map();
+	_abortController = new AbortController();
+	_idLogger;
+	_inFlight = /* @__PURE__ */ new Map();
+	_readyDeferred = createDeferred$1();
+	_readyError;
+	_readyState = "pending";
+	get logger() {
+		this._idLogger ??= new IdLogger(assertEx(this.context.logger, () => `Logger is required in context for actor ${this.name}.`), () => this.name);
+		return this._idLogger;
+	}
+	get readyError() {
+		return this._readyError;
+	}
+	get readyState() {
+		return this._readyState;
+	}
+	get context() {
+		return this.locator.context;
+	}
+	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({
+			...inParams,
+			name: inParams.name ?? "UnknownActor"
+		});
+		const locator = assertEx(inParams.locator, () => `params.locator is required for actor ${String(baseParams.name)}.`);
+		return {
+			...baseParams,
+			locator
+		};
+	}
+	/** Override to prove the actor can do useful work. Default: no-op. */
+	async readyHandler() {}
+	/**
+	* 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") {
+			this.logger.warn(`Cannot register timer '${timerName}' because actor is not starting.`);
+			return;
+		}
+		const tick = () => {
+			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;
+			}
+			const run = (async () => {
+				const startTime = Date.now();
+				try {
+					await callback();
+				} catch (error) {
+					const err = error instanceof Error ? error : new Error(String(error));
+					this.logger.error(`Error in timer '${this.name}:${timerName}': ${err.message}`);
+				} finally {
+					const duration = Date.now() - startTime;
+					if (duration > periodMs) this.logger.warn(`Timer '${this.name}:${timerName}' took ${duration}ms, longer than its ${periodMs}ms period.`);
+				}
+			})();
+			this._inFlight.set(timerName, run.finally(() => {
+				this._inFlight.delete(timerName);
+			}));
+		};
+		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. The standard boot path invokes this after
+	* `start()` so readiness either resolves or rejects.
+	*/
+	async runReadyHandler() {
+		if (this._readyState !== "pending") return;
+		try {
+			await this.readyHandler();
+			this._readyState = "ready";
+			this._readyDeferred.resolve();
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
+			this._readyState = "failed";
+			this._readyError = err;
+			this._readyDeferred.reject(err);
+			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();
+		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;
+	}
+};
+//#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
+* `static dependencies` and resolves them from the locator at create time.
+*/
+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;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#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,
+		DappStateStoreMoniker,
+		DappIndexStoreMoniker
+	];
+	_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();
+		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(REDUCE_TIMER, async () => {
+			await this.runReducePass();
+		}, firstRunDelay, interval);
+		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() {
+		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);
+//#endregion
+//#region src/boot/bootDappActors.ts
+/**
+* Creates and starts one {@link DappActor} per spec, all sharing the single
+* 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 = [];
+	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;
+	}
+};
+//#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;
+	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}. 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 { 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 metaFromResponse(await client.send(new HeadObjectCommand({
+					Bucket: bucket,
+					Key: resolve(key)
+				})));
+			} catch (error) {
+				if (isNotFound(error)) return void 0;
+				throw error;
+			}
+		},
+		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: 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 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);
+		}
+	};
+}
+//#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 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 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);
+	};
+	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) {
+			return instances.has(moniker);
+		},
+		register(moniker, instance) {
+			instances.set(moniker, instance);
+		},
+		async getInstance(moniker) {
+			const found = instances.get(moniker);
+			if (found === void 0) throw new Error(`No provider registered for moniker "${moniker}"`);
+			return found;
+		},
+		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 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",
+	async reduce() {}
+};
+//#endregion
+//#region src/bin/loadReducer.ts
+const require = createRequire(import.meta.url);
+function isPathSpec(spec) {
+	return spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("file:") || path.isAbsolute(spec) || spec.endsWith(".mjs") || spec.endsWith(".js") || spec.endsWith(".cjs");
+}
+function resolveFileUrl(spec) {
+	if (spec.startsWith("file:")) return spec;
+	const absolute = path.isAbsolute(spec) ? spec : path.resolve(process.cwd(), spec);
+	if (!existsSync(absolute)) throw new Error(`Reducer module not found: ${absolute}`);
+	return pathToFileURL(absolute).href;
+}
+function resolvePackageUrl(spec) {
+	try {
+		return pathToFileURL(require.resolve(spec, { paths: [process.cwd()] })).href;
+	} catch {
+		throw new Error(`Could not resolve reducer package "${spec}" from ${process.cwd()}. Pass a path to a .mjs file or an installed package export.`);
+	}
+}
+function pickReducer(mod, exportName) {
+	if (exportName !== void 0 && exportName.length > 0) {
+		if (!(exportName in mod)) throw new Error(`Reducer module has no export named "${exportName}"`);
+		return mod[exportName];
+	}
+	if (mod.default !== void 0) return mod.default;
+	if (mod.reducer !== void 0) return mod.reducer;
+	throw new Error("Reducer module must default-export a DappReducer, or export `reducer`, or set DAPP_REDUCER_EXPORT / --reducer-export to a named export");
+}
+function assertReducer(value, label) {
+	if (value === null || typeof value !== "object") throw new TypeError(`${label} is not an object`);
+	const candidate = value;
+	if (typeof candidate.name !== "string" || candidate.name.length === 0) throw new TypeError(`${label} must have a non-empty string "name"`);
+	if (typeof candidate.reduce !== "function") throw new TypeError(`${label} must have a "reduce" function`);
+	return candidate;
+}
+/**
+* Dynamically load a project-owned reducer for the local dapp daemon.
+* Supports filesystem `.mjs`/`.js` paths and package export strings.
+* TypeScript sources are not supported — build to ESM first.
+*/
+async function loadReducer(options) {
+	return assertReducer(pickReducer(await (isPathSpec(options.spec) ? import(resolveFileUrl(options.spec)) : import(resolvePackageUrl(options.spec))), options.exportName), `Reducer from ${options.spec}`);
+}
+//#endregion
+//#region src/bin/dappServer.ts
+/**
+* **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 DappActor(s).
+* Spawned by `aries dapp up`.
+*
+* Optional `DAPP_REDUCER` loads a project-owned ESM reducer (`.mjs` path or
+* package export). Without it, `noopReducer` runs so the spine still works.
+*
+* Production indexers should **not** use this binary. Compose `dapp-core` from
+* a project-owned entrypoint with real R2/S3 bindings and a real reducer —
+* see the package README and `examples/`.
+*/
+const PORT = Number(process.env.DAPP_PORT ?? 8801);
+const HOST = process.env.HOST ?? "127.0.0.1";
+const BACKING = process.env.DAPP_BACKING ?? "memory";
+const PUBLIC_HOST = process.env.DAPP_PUBLIC_HOST;
+const TLS_CERT_PATH = process.env.DAPP_TLS_CERT;
+const TLS_KEY_PATH = process.env.DAPP_TLS_KEY;
+const REDUCE_INTERVAL_MS = Number(process.env.DAPP_REDUCE_INTERVAL_MS ?? 5e3);
+const FIRST_RUN_DELAY_MS = Number(process.env.DAPP_FIRST_RUN_DELAY_MS ?? 0);
+const REDUCER_SPEC = process.env.DAPP_REDUCER;
+const REDUCER_EXPORT = process.env.DAPP_REDUCER_EXPORT;
+const DATA_DIR = process.env.DAPP_DATA_DIR ?? path.join(process.env.ARIES_HOME ?? path.join(homedir(), ".aries"), "dapp", "data");
+async function resolveDaemonReducer() {
+	if (REDUCER_SPEC === void 0 || REDUCER_SPEC.length === 0) return noopReducer;
+	return await loadReducer({
+		spec: REDUCER_SPEC,
+		...REDUCER_EXPORT !== void 0 && REDUCER_EXPORT.length > 0 && { exportName: REDUCER_EXPORT }
+	});
+}
+async function main() {
+	if (!isDappBackingKind(BACKING)) throw new Error(`Unsupported DAPP_BACKING '${BACKING}' (supported: ${DAPP_BACKINGS.join(", ")})`);
+	if (TLS_CERT_PATH === void 0 !== (TLS_KEY_PATH === void 0)) throw new Error("DAPP_TLS_CERT and DAPP_TLS_KEY must be provided together");
+	const reducer = await resolveDaemonReducer();
+	const backing = resolveBacking(BACKING, { ...BACKING === "disk" && { directory: DATA_DIR } });
+	const server = await startDappServer({
+		backing,
+		host: HOST,
+		port: PORT,
+		publicHost: PUBLIC_HOST,
+		tls: TLS_CERT_PATH === void 0 || TLS_KEY_PATH === void 0 ? void 0 : {
+			cert: readFileSync(TLS_CERT_PATH),
+			key: readFileSync(TLS_KEY_PATH)
+		}
+	});
+	const logger = new ConsoleLogger();
+	const locator = createDappLocator({
+		endpoint: server.baseUrl,
+		logger,
+		readOnlyData: false
+	});
+	process.env.DAPP_PUBLICATION_SAFETY ??= "unfenced";
+	process.env.DAPP_ENDPOINT ??= server.baseUrl;
+	const actors = await bootDappActors(locator, [{
+		name: "DappActor",
+		reducer,
+		reduceIntervalMs: REDUCE_INTERVAL_MS,
+		firstRunDelayMs: FIRST_RUN_DELAY_MS,
+		publishStatus: reducer.name !== "noop"
+	}]);
+	const versionSuffix = reducer.version === void 0 ? "" : `@${reducer.version}`;
+	const reducerLine = REDUCER_SPEC === void 0 ? "\nreducer: noop (pass DAPP_REDUCER / --reducer for real logic)" : `\nreducer: ${REDUCER_SPEC}`;
+	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}\nactors: ${actors.length} (reducer '${reducer.name}'${versionSuffix}, every ${REDUCE_INTERVAL_MS}ms)` + reducerLine);
+	const shutdown = async () => {
+		for (const actor of actors) await actor.stop();
+		locator.destroy();
+		await server.close();
+		process.exit(0);
+	};
+	process.on("SIGINT", () => {
+		shutdown();
+	});
+	process.on("SIGTERM", () => {
+		shutdown();
+	});
+}
+main().catch((error) => {
+	console.error(error);
+	process.exit(1);
+});
+//#endregion
+export {};