@ariestools/aries-dapp-core 0.1.7 → 0.1.8

package/dist/node/index.mjs

@@ -24,6 +24,8 @@ function createDeferred() {
     resolve = res;
     reject = rej;
   });
+  void promise.catch(() => {
+  });
   return {
     promise,
     reject,
@@ -33,6 +35,7 @@ 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();
@@ -57,17 +60,25 @@ 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({ ...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 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") {
@@ -75,7 +86,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 +110,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,60 +134,310 @@ 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() {
-  }
 };
 
 // src/DappActor.ts
 import { creatable } from "@ariestools/sdk";
 
+// src/providers/capabilities.ts
+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)
+  };
+}
+function asReadOnly(store) {
+  return bindReader(store);
+}
+function asReadOnlyWriter(store) {
+  const reader = bindReader(store);
+  return {
+    ...reader,
+    async put() {
+      throw new ReadOnlyStoreError(store.role, "put");
+    },
+    async delete() {
+      throw new ReadOnlyStoreError(store.role, "delete");
+    }
+  };
+}
+
 // src/providers/monikers.ts
 var DappDataStoreMoniker = "DappDataStore";
 var DappStateStoreMoniker = "DappStateStore";
 var DappIndexStoreMoniker = "DappIndexStore";
 
+// src/publication/constants.ts
+var HEAD_KEY = "head.json";
+var STATUS_KEY = "status.json";
+var PINS_KEY = "pins.json";
+var GENERATIONS_PREFIX = "generations";
+var CAS_PREFIX = "cas/sha256";
+var MAP_ROOTS_PREFIX = "map/roots";
+var MAP_SHARDS_PREFIX = "map/shards";
+var RECEIPTS_PREFIX = "receipts";
+var CACHE_CONTROL_IMMUTABLE = "public, max-age=31536000, immutable";
+var CACHE_CONTROL_REVALIDATE = "public, max-age=0, must-revalidate";
+var GENERATION_MANIFEST_SCHEMA = "network.aries.dapp.generation.manifest";
+var HEAD_MANIFEST_SCHEMA = "network.aries.dapp.head";
+var INDEXER_STATUS_SCHEMA = "network.aries.dapp.indexer.status";
+var PINS_SCHEMA = "network.aries.dapp.pins";
+var MAP_ROOT_SCHEMA = "network.aries.dapp.map.root";
+var MAP_SHARD_SCHEMA = "network.aries.dapp.map.shard";
+var RECEIPT_SCHEMA = "network.aries.dapp.generation.receipt";
+var DEFAULT_SHARD_HEX_CHARS = 2;
+
+// src/publication/status.ts
+function encodeStatus(status) {
+  return `${JSON.stringify(status, null, 2)}
+`;
+}
+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 !== INDEXER_STATUS_SCHEMA) {
+    throw new Error(`Invalid indexer status schema at "${key}": ${String(record.schema)}`);
+  }
+  return record;
+}
+async function writeIndexerStatus(store, input) {
+  const key = input.key ?? STATUS_KEY;
+  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;
+}
+
+// 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;
+}
+var PROGRESS_KEYS = [
+  "floor",
+  "cursor",
+  "lastCompletedPosition",
+  "observedSourceHead",
+  "generation",
+  "generationRoot"
+];
+function priorProgressFields(prior) {
+  if (prior === void 0) return {};
+  return {
+    ...pickDefined(prior, PROGRESS_KEYS),
+    ...prior.lastSuccessAt !== void 0 && { lastSuccessAt: prior.lastSuccessAt }
+  };
+}
+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 }
+  };
+}
+function failureStatusFields(prior, consecutiveFailures, error, now) {
+  return {
+    consecutiveFailures,
+    ...priorProgressFields(prior),
+    lastError: error.message,
+    lastErrorAt: now
+  };
+}
+
 // src/DappActor.ts
 var DEFAULT_REDUCE_INTERVAL_MS = 5e3;
 var DEFAULT_FIRST_RUN_DELAY_MS = 2e3;
+var REDUCE_TIMER = "DappReduce";
+function createDeferred2() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  void 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 };
+}
 var DappActor = class extends AbstractActor {
   _data;
   _index;
   _state;
+  _consecutiveFailures = 0;
+  _firstPass = createDeferred2();
+  _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(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(() => {
+          void 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);
   }
 };
 __publicField(DappActor, "dependencies", [
@@ -189,18 +452,35 @@ DappActor = __decorateClass([
 // src/boot/bootDappActors.ts
 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;
   }
-  return actors;
 }
 
 // src/locator/createDappLocator.ts
@@ -208,77 +488,318 @@ import { ConsoleLogger } from "@ariestools/sdk";
 
 // src/providers/DappBucketStore.ts
 import {
+  DeleteObjectCommand,
   GetObjectCommand,
+  HeadObjectCommand,
   ListObjectsV2Command,
   PutObjectCommand,
   S3Client
 } from "@aws-sdk/client-s3";
+
+// src/providers/errors.ts
+var ConditionalWriteError = class extends Error {
+  key;
+  name = "ConditionalWriteError";
+  constructor(key, message) {
+    super(message ?? `Conditional write failed for key "${key}"`);
+    this.key = key;
+  }
+};
+function isConditionalWriteError(error) {
+  return error instanceof ConditionalWriteError || error !== null && typeof error === "object" && error.name === "ConditionalWriteError";
+}
+
+// src/providers/joinKey.ts
+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}`;
+}
+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;
+}
+function normalizePublicBaseUrl(url) {
+  if (url === void 0 || url.length === 0) return void 0;
+  return url.replace(/\/+$/, "");
+}
+
+// src/providers/DappBucketStore.ts
 var DEFAULT_CREDENTIAL = "S3RVER";
+var 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 createS3BucketStore(options) {
-  const { bucket } = options;
+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 }
+  };
+}
+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);
   const client = new S3Client({
-    endpoint: options.endpoint,
-    region: "us-east-1",
-    forcePathStyle: true,
-    credentials: {
-      accessKeyId: options.accessKeyId ?? DEFAULT_CREDENTIAL,
-      secretAccessKey: options.secretAccessKey ?? DEFAULT_CREDENTIAL
-    }
+    ...options.endpoint !== void 0 && { endpoint: options.endpoint },
+    region: options.region ?? DEFAULT_REGION,
+    forcePathStyle: options.forcePathStyle ?? options.endpoint !== void 0,
+    ...credentials !== void 0 && { credentials }
   });
   return {
+    client,
+    ownClient: options.ownClient ?? true
+  };
+}
+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) {
+      const result = await this.getWithMeta(key);
+      return result?.body;
+    },
+    async getWithMeta(key) {
       try {
-        const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
-        return await response.Body?.transformToByteArray();
+        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 put(key, body) {
-      await client.send(new PutObjectCommand({
+    async stat(key) {
+      try {
+        const response = await client.send(new HeadObjectCommand({
+          Bucket: bucket,
+          Key: resolve(key)
+        }));
+        return metaFromResponse(response);
+      } 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: 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;
     }
   };
 }
 
 // src/locator/createDappLocator.ts
+var DEFAULT_BINDINGS = {
+  data: { bucket: "data" },
+  state: { bucket: "state" },
+  index: { bucket: "index" }
+};
+var 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"
+    };
+  }
+  return void 0;
+}
+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,
+    // Per-role constructed clients are owned by the locator.
+    ownClient: override.ownClient ?? true
+  });
+}
 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 instances = /* @__PURE__ */ new Map([
-    [DappDataStoreMoniker, createS3BucketStore({ ...bucketOptions, bucket: "data" })],
-    [DappStateStoreMoniker, createS3BucketStore({ ...bucketOptions, bucket: "state" })],
-    [DappIndexStoreMoniker, createS3BucketStore({ ...bucketOptions, bucket: "index" })]
-  ]);
+  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,
+      // Locator owns clients; individual stores must not destroy them.
+      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) {
@@ -294,7 +815,1101 @@ 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();
+      }
+    }
+  };
+}
+
+// src/providers/hashBytes.ts
+import { createHash } from "node:crypto";
+function hashBytes(body) {
+  const hash = createHash("sha256");
+  hash.update(typeof body === "string" ? body : Buffer.from(body));
+  return hash.digest("hex");
+}
+
+// src/providers/memoryBucketStore.ts
+function createMemoryBucketStore(options) {
+  const objects = /* @__PURE__ */ new Map();
+  let etagSeq = 0;
+  const role = options.role;
+  const bucket = options.bucket ?? role;
+  const prefix = (options.prefix ?? "").replaceAll(/^\/+|\/+$/g, "");
+  const publicBaseUrl = options.publicBaseUrl;
+  function nextEtag() {
+    etagSeq += 1;
+    return `"mem-${etagSeq}"`;
+  }
+  function toBytes4(body) {
+    return typeof body === "string" ? new TextEncoder().encode(body) : body;
+  }
+  return {
+    role,
+    bucket,
+    prefix,
+    ...publicBaseUrl !== void 0 && { publicBaseUrl },
+    destroy() {
+      objects.clear();
+    },
+    resolveKey(key) {
+      const clean = key.replaceAll(/^\/+/g, "");
+      if (prefix.length === 0) return clean;
+      return clean.length === 0 ? prefix : `${prefix}/${clean}`;
+    },
+    publicUrl(key) {
+      if (publicBaseUrl === void 0) return void 0;
+      const relative = key.replaceAll(/^\/+/g, "");
+      return relative.length === 0 ? publicBaseUrl : `${publicBaseUrl}/${relative}`;
+    },
+    async get(key) {
+      return objects.get(key)?.body;
+    },
+    async getWithMeta(key) {
+      const found = objects.get(key);
+      if (found === void 0) return void 0;
+      return {
+        body: found.body,
+        meta: {
+          etag: found.etag,
+          ...found.contentType !== void 0 && { contentType: found.contentType },
+          ...found.contentEncoding !== void 0 && { contentEncoding: found.contentEncoding },
+          ...found.cacheControl !== void 0 && { cacheControl: found.cacheControl },
+          contentLength: found.body.byteLength,
+          ...found.metadata !== void 0 && { metadata: found.metadata }
+        }
+      };
+    },
+    async stat(key) {
+      const found = objects.get(key);
+      if (found === void 0) return void 0;
+      return {
+        etag: found.etag,
+        contentLength: found.body.byteLength,
+        ...found.contentType !== void 0 && { contentType: found.contentType },
+        ...found.cacheControl !== void 0 && { cacheControl: found.cacheControl }
+      };
+    },
+    async put(key, body, putOptions) {
+      const existing = objects.get(key);
+      if (putOptions?.ifNotExists === true && existing !== void 0) {
+        throw new ConditionalWriteError(key);
+      }
+      if (putOptions?.ifMatch !== void 0 && (existing === void 0 || existing.etag !== putOptions.ifMatch)) {
+        throw new ConditionalWriteError(key);
+      }
+      const etag = nextEtag();
+      objects.set(key, {
+        body: toBytes4(body),
+        etag,
+        ...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 }
+      });
+      return { etag };
+    },
+    async delete(key) {
+      objects.delete(key);
+    },
+    async list(listPrefix) {
+      const keys = [];
+      for await (const key of this.listAsync(listPrefix)) keys.push(key);
+      return keys;
+    },
+    async listPage(pageOptions = {}) {
+      const p = pageOptions.prefix ?? "";
+      let keys = [...objects.keys()].filter((k) => k.startsWith(p)).sort();
+      if (pageOptions.continuationToken !== void 0) {
+        const idx = keys.indexOf(pageOptions.continuationToken);
+        keys = idx === -1 ? keys : keys.slice(idx + 1);
+      }
+      const max = pageOptions.maxKeys ?? keys.length;
+      const page = keys.slice(0, max);
+      const isTruncated = keys.length > max;
+      return {
+        keys: page,
+        isTruncated,
+        ...isTruncated && page.length > 0 && { continuationToken: page.at(-1) }
+      };
+    },
+    async *listAsync(listPrefix) {
+      let token;
+      do {
+        const page = await this.listPage({
+          ...listPrefix !== void 0 && { prefix: listPrefix },
+          ...token !== void 0 && { continuationToken: token },
+          maxKeys: 100
+        });
+        for (const key of page.keys) yield key;
+        token = page.continuationToken;
+      } while (token !== void 0);
+    }
+  };
+}
+
+// src/providers/types.ts
+var DAPP_STORE_ROLES = ["data", "state", "index"];
+
+// src/publication/canonicalHead.ts
+function canonicalHeadBytes(head) {
+  const payload = {
+    schema: head.schema,
+    generation: head.generation,
+    manifestKey: head.manifestKey,
+    manifestHash: head.manifestHash,
+    publishedAt: head.publishedAt
+  };
+  if (head.previousGeneration !== void 0) {
+    payload.previousGeneration = head.previousGeneration;
+  }
+  if (head.revision !== void 0) payload.revision = head.revision;
+  if (head.trust !== void 0) payload.trust = head.trust;
+  if (head.layout !== void 0) payload.layout = head.layout;
+  const ordered = {};
+  for (const key of [
+    "schema",
+    "generation",
+    "manifestKey",
+    "manifestHash",
+    "publishedAt",
+    "previousGeneration",
+    "revision",
+    "trust",
+    "layout"
+  ]) {
+    if (key in payload) ordered[key] = payload[key];
+  }
+  return new TextEncoder().encode(`${JSON.stringify(ordered)}
+`);
+}
+
+// src/publication/publishGeneration.ts
+import { randomUUID } from "node:crypto";
+
+// src/publication/commitHead.ts
+async function commitHead(state, head, safety, fenced, expectedHeadEtag) {
+  const headBody = `${JSON.stringify(head, null, 2)}
+`;
+  const base = {
+    contentType: "application/json",
+    cacheControl: CACHE_CONTROL_REVALIDATE
+  };
+  try {
+    if (!fenced) {
+      return await state.put(HEAD_KEY, headBody, base);
+    }
+    if (expectedHeadEtag === void 0) {
+      return await state.put(HEAD_KEY, headBody, { ...base, ifNotExists: true });
+    }
+    return await state.put(HEAD_KEY, headBody, { ...base, ifMatch: expectedHeadEtag });
+  } catch (error) {
+    if (error instanceof ConditionalWriteError) {
+      return {
+        conflict: {
+          kind: safety.mode === "lease" ? "lease" : "head-cas",
+          message: `Head publish conflict on "${HEAD_KEY}" (stale or concurrent writer)`,
+          key: HEAD_KEY
+        }
+      };
+    }
+    throw error;
+  }
+}
+
+// src/publication/safety.ts
+var PROBE_PREFIX = ".aries-dapp-probe/";
+async function probePublicationCapabilities(store) {
+  const key = `${PROBE_PREFIX}${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  let conditionalCreate = false;
+  let conditionalUpdate = false;
+  try {
+    const created = await store.put(key, "probe-v1", {
+      ifNotExists: true,
+      contentType: "text/plain"
+    });
+    try {
+      await store.put(key, "probe-v1-again", { ifNotExists: true });
+    } catch (error) {
+      conditionalCreate = error instanceof ConditionalWriteError;
+    }
+    const etag = created.etag;
+    if (etag !== void 0) {
+      try {
+        await store.put(key, "probe-v2", {
+          ifMatch: etag,
+          contentType: "text/plain"
+        });
+        try {
+          await store.put(key, "probe-stale", {
+            ifMatch: '"not-the-etag"',
+            contentType: "text/plain"
+          });
+        } catch (error) {
+          conditionalUpdate = error instanceof ConditionalWriteError;
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+  try {
+    await store.put(key, "", { contentType: "text/plain" });
+  } catch {
+  }
+  return { conditionalCreate, conditionalUpdate };
+}
+async function assertPublicationSafety(store, safety, capabilities) {
+  if (safety.mode === "unfenced") {
+    return { conditionalCreate: false, conditionalUpdate: false };
+  }
+  if (safety.mode === "lease") {
+    return capabilities ?? await probePublicationCapabilities(store);
+  }
+  const caps = capabilities ?? await probePublicationCapabilities(store);
+  if (!caps.conditionalCreate || !caps.conditionalUpdate) {
+    throw new Error(
+      'Publication safety mode "conditional-head" requires provider support for create-only (If-None-Match: *) and conditional update (If-Match). Probe failed; refuse to publish without fencing. Use an injected lease adapter, or fix provider configuration.'
+    );
+  }
+  return caps;
+}
+
+// src/publication/putCreateOnly.ts
+function toBytes(body) {
+  return typeof body === "string" ? new TextEncoder().encode(body) : body;
+}
+function bytesEqual(a, b) {
+  if (a.byteLength !== b.byteLength) return false;
+  for (let i = 0; i < a.byteLength; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+async function putCreateOnly(store, key, body, options) {
+  const bytes = toBytes(body);
+  const hash = hashBytes(bytes);
+  try {
+    const result = await store.put(key, bytes, {
+      ...options,
+      ifNotExists: true
+    });
+    return { ...result, hash };
+  } catch (error) {
+    if (!(error instanceof ConditionalWriteError)) throw error;
+    const existing = await store.get(key);
+    if (existing === void 0) {
+      throw new Error(
+        `Immutable create-only collision on "${key}" (object missing after precondition failure)`,
+        { cause: error }
+      );
+    }
+    if (bytesEqual(existing, bytes)) {
+      const meta = await store.stat(key);
+      return { hash, ...meta?.etag !== void 0 && { etag: meta.etag } };
+    }
+    throw new Error(
+      `Immutable create-only collision on "${key}": existing bytes differ (wanted hash ${hash}, existing hash ${hashBytes(existing)})`,
+      { cause: error }
+    );
+  }
+}
+
+// src/publication/writeGenerationObjects.ts
+function assertNotAborted(signal) {
+  if (signal?.aborted === true) {
+    throw new Error("Publication aborted");
+  }
+}
+function toBytes2(body) {
+  return typeof body === "string" ? new TextEncoder().encode(body) : body;
+}
+async function writeImmutableObjects(store, role, generation, objects, signal, fenced) {
+  const refs = [];
+  for (const object of objects) {
+    assertNotAborted(signal);
+    const relativeKey = `${GENERATIONS_PREFIX}/${generation}/${object.key.replaceAll(/^\/+/g, "")}`;
+    const bytes = toBytes2(object.body);
+    const contentType = object.contentType ?? "application/json";
+    const putOpts = {
+      contentType,
+      cacheControl: CACHE_CONTROL_IMMUTABLE,
+      ...object.metadata !== void 0 && { metadata: object.metadata }
+    };
+    let hash;
+    if (fenced) {
+      hash = (await putCreateOnly(store, relativeKey, bytes, putOpts)).hash;
+    } else {
+      hash = hashBytes(bytes);
+      await store.put(relativeKey, bytes, putOpts);
+    }
+    const publicUrl = store.publicUrl(relativeKey);
+    refs.push({
+      role,
+      key: relativeKey,
+      hash,
+      size: bytes.byteLength,
+      contentType,
+      ...publicUrl !== void 0 && { publicUrl }
+    });
+  }
+  return refs;
+}
+async function writeManifest(store, manifestKey, manifestBody, fenced) {
+  const opts = {
+    contentType: "application/json",
+    cacheControl: CACHE_CONTROL_IMMUTABLE
+  };
+  if (fenced) {
+    await putCreateOnly(store, manifestKey, manifestBody, opts);
+    return;
+  }
+  await store.put(manifestKey, manifestBody, opts);
+}
+
+// src/publication/publishGeneration.ts
+function assertNotAborted2(signal) {
+  if (signal?.aborted === true) {
+    throw new Error("Publication aborted");
+  }
+}
+async function acquireLeaseIfNeeded(input) {
+  if (input.safety.mode !== "lease") return void 0;
+  return await input.safety.lease.acquire({
+    key: HEAD_KEY,
+    ttlMs: 6e4,
+    ...input.signal !== void 0 && { signal: input.signal }
+  });
+}
+async function buildAndSignHead(input, generation, manifestKey, manifestHash, publishedAt) {
+  const trustMode = input.trust?.mode ?? "trusted-origin";
+  const head = {
+    schema: HEAD_MANIFEST_SCHEMA,
+    generation,
+    layout: "full",
+    manifestKey,
+    manifestHash,
+    publishedAt,
+    trust: trustMode,
+    ...input.previousGeneration !== void 0 && { previousGeneration: input.previousGeneration },
+    ...input.revision !== void 0 && { revision: input.revision }
+  };
+  if (input.trust?.mode === "signed") {
+    head.signature = await input.trust.sign(canonicalHeadBytes(head));
+  }
+  return head;
+}
+async function writeObjectsAndManifest(input, generation, fenced) {
+  const signal = input.signal;
+  const stateRefs = await writeImmutableObjects(input.state, "state", generation, input.stateObjects ?? [], signal, fenced);
+  const indexRefs = await writeImmutableObjects(input.index, "index", generation, input.indexObjects ?? [], signal, fenced);
+  const publishedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const manifest = {
+    schema: GENERATION_MANIFEST_SCHEMA,
+    generation,
+    publishedAt,
+    reducer: {
+      name: input.reducer.name,
+      ...input.reducer.version !== void 0 && { version: input.reducer.version }
+    },
+    ...input.schemaVersion !== void 0 && { schemaVersion: input.schemaVersion },
+    source: input.source ?? {},
+    objects: [...stateRefs, ...indexRefs]
+  };
+  const manifestKey = `${GENERATIONS_PREFIX}/${generation}/manifest.json`;
+  const manifestBody = `${JSON.stringify(manifest, null, 2)}
+`;
+  const manifestHash = hashBytes(manifestBody);
+  assertNotAborted2(signal);
+  try {
+    await writeManifest(input.state, manifestKey, manifestBody, fenced);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("Immutable create-only collision")) {
+      return {
+        ok: false,
+        conflict: {
+          kind: "immutable-collision",
+          message: error.message,
+          key: manifestKey
+        }
+      };
+    }
+    throw error;
+  }
+  return {
+    ok: true,
+    manifest,
+    manifestKey,
+    manifestHash
+  };
+}
+async function releaseLease(handle) {
+  if (handle === void 0) return;
+  try {
+    await handle.release();
+  } catch {
+  }
+}
+async function publishGeneration(input) {
+  const generation = input.generation ?? randomUUID();
+  const signal = input.signal;
+  assertNotAborted2(signal);
+  if (input.assertSafety !== false && input.safety.mode === "conditional-head") {
+    await assertPublicationSafety(input.state, input.safety);
+  }
+  const fenced = input.safety.mode !== "unfenced";
+  const leaseHandle = await acquireLeaseIfNeeded(input);
+  try {
+    const written = await writeObjectsAndManifest(input, generation, fenced);
+    if (!written.ok) return written;
+    const head = await buildAndSignHead(input, generation, written.manifestKey, written.manifestHash, written.manifest.publishedAt);
+    assertNotAborted2(signal);
+    const committed = await commitHead(input.state, head, input.safety, fenced, input.expectedHeadEtag);
+    if ("conflict" in committed) {
+      return { ok: false, conflict: committed.conflict };
+    }
+    return {
+      ok: true,
+      generation,
+      manifest: written.manifest,
+      manifestKey: written.manifestKey,
+      manifestHash: written.manifestHash,
+      head,
+      headKey: HEAD_KEY,
+      ...committed.etag !== void 0 && { headEtag: committed.etag }
+    };
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("Immutable create-only collision")) {
+      return {
+        ok: false,
+        conflict: {
+          kind: "immutable-collision",
+          message: error.message
+        }
+      };
+    }
+    if (signal?.aborted === true) {
+      return {
+        ok: false,
+        conflict: {
+          kind: "aborted",
+          message: error instanceof Error ? error.message : "Publication aborted"
+        }
+      };
+    }
+    throw error;
+  } finally {
+    await releaseLease(leaseHandle);
+  }
+}
+async function readPublishedHead(state) {
+  const withMeta = await state.getWithMeta(HEAD_KEY);
+  if (withMeta === void 0) return void 0;
+  const head = JSON.parse(new TextDecoder().decode(withMeta.body));
+  if (head.schema !== HEAD_MANIFEST_SCHEMA) {
+    throw new Error(`Invalid head schema: ${String(head.schema)}`);
+  }
+  const targetBody = await state.get(head.manifestKey);
+  if (targetBody === void 0) {
+    throw new Error(`Head points at missing object "${head.manifestKey}"`);
+  }
+  const targetBytes = typeof targetBody === "string" ? new TextEncoder().encode(targetBody) : targetBody;
+  const actualHash = hashBytes(targetBytes);
+  if (actualHash !== head.manifestHash) {
+    throw new Error(
+      `Head target hash mismatch for generation "${head.generation}": head=${head.manifestHash} actual=${actualHash}`
+    );
+  }
+  if (head.layout === "incremental-cas") {
+    return {
+      head,
+      ...withMeta.meta.etag !== void 0 && { headEtag: withMeta.meta.etag }
+    };
+  }
+  const manifest = JSON.parse(new TextDecoder().decode(targetBytes));
+  if (manifest.schema !== GENERATION_MANIFEST_SCHEMA) {
+    throw new Error(`Invalid generation manifest schema: ${String(manifest.schema)}`);
+  }
+  if (manifest.generation !== head.generation) {
+    throw new Error(
+      `Generation id mismatch: head=${head.generation} manifest=${manifest.generation}`
+    );
+  }
+  return {
+    head,
+    manifest,
+    ...withMeta.meta.etag !== void 0 && { headEtag: withMeta.meta.etag }
+  };
+}
+
+// src/publication/releases.ts
+async function readPins(state) {
+  const found = await state.getWithMeta(PINS_KEY);
+  if (found === void 0) {
+    return {
+      doc: {
+        schema: PINS_SCHEMA,
+        pins: [],
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    };
+  }
+  const doc = JSON.parse(new TextDecoder().decode(found.body));
+  return {
+    doc,
+    ...found.meta.etag !== void 0 && { etag: found.meta.etag }
+  };
+}
+async function writePins(state, doc, expectedEtag) {
+  const body = `${JSON.stringify(doc, null, 2)}
+`;
+  const opts = {
+    contentType: "application/json",
+    cacheControl: CACHE_CONTROL_REVALIDATE,
+    ...expectedEtag === void 0 ? { ifNotExists: true } : { ifMatch: expectedEtag }
+  };
+  try {
+    await state.put(PINS_KEY, body, opts);
+  } catch (error) {
+    if (error instanceof ConditionalWriteError && expectedEtag === void 0) {
+    }
+    throw error;
+  }
+}
+async function listReleases(state) {
+  const byGen = /* @__PURE__ */ new Map();
+  for await (const key of state.listAsync(`${GENERATIONS_PREFIX}/`)) {
+    const parts = key.split("/");
+    if (parts.length < 3 || parts[0] !== GENERATIONS_PREFIX) continue;
+    const generation = parts[1];
+    const existing = byGen.get(generation) ?? { generation, kind: "full" };
+    if (parts[2] === "manifest.json") {
+      existing.manifestKey = key;
+      existing.kind = "full";
+    }
+    byGen.set(generation, existing);
+  }
+  for await (const key of state.listAsync(`${RECEIPTS_PREFIX}/`)) {
+    const base = key.slice(RECEIPTS_PREFIX.length + 1).replace(/\.json$/, "");
+    if (base.length === 0) continue;
+    const existing = byGen.get(base) ?? { generation: base, kind: "incremental" };
+    existing.receiptKey = key;
+    if (existing.manifestKey === void 0) existing.kind = "incremental";
+    byGen.set(base, existing);
+  }
+  return [...byGen.values()].sort((a, b) => a.generation.localeCompare(b.generation));
+}
+async function pinRelease(state, generation, opts) {
+  const { doc, etag } = await readPins(state);
+  if (doc.pins.some((p) => p.generation === generation)) return doc;
+  const next = {
+    schema: PINS_SCHEMA,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    pins: [
+      ...doc.pins,
+      {
+        generation,
+        pinnedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        ...opts?.reason !== void 0 && { reason: opts.reason }
+      }
+    ]
+  };
+  await writePins(state, next, etag);
+  return next;
+}
+async function unpinRelease(state, generation) {
+  const { doc, etag } = await readPins(state);
+  const next = {
+    schema: PINS_SCHEMA,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    pins: doc.pins.filter((p) => p.generation !== generation)
+  };
+  await writePins(state, next, etag);
+  return next;
+}
+async function listPins(state) {
+  return (await readPins(state)).doc.pins;
+}
+async function rollbackHead(state, input) {
+  const current = await readPublishedHead(state);
+  if (current === void 0) {
+    return { ok: false, message: "No current head to roll back" };
+  }
+  if (current.head.generation === input.targetGeneration) {
+    return {
+      ok: true,
+      head: current.head,
+      ...current.headEtag !== void 0 && { headEtag: current.headEtag }
+    };
+  }
+  const manifestKey = `${GENERATIONS_PREFIX}/${input.targetGeneration}/manifest.json`;
+  const receiptKey = `${RECEIPTS_PREFIX}/${input.targetGeneration}.json`;
+  const manifestBody = await state.get(manifestKey);
+  const receiptBody = manifestBody === void 0 ? await state.get(receiptKey) : void 0;
+  let head;
+  if (manifestBody !== void 0) {
+    const bytes = typeof manifestBody === "string" ? new TextEncoder().encode(manifestBody) : manifestBody;
+    const parsed = JSON.parse(new TextDecoder().decode(bytes));
+    if (parsed.generation !== input.targetGeneration) {
+      return { ok: false, message: "Target manifest generation mismatch" };
+    }
+    head = {
+      schema: HEAD_MANIFEST_SCHEMA,
+      generation: input.targetGeneration,
+      manifestKey,
+      manifestHash: hashBytes(bytes),
+      publishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      previousGeneration: current.head.generation,
+      trust: current.head.trust ?? "trusted-origin",
+      revision: (current.head.revision ?? 1) + 1,
+      layout: "full"
+    };
+  } else if (receiptBody === void 0) {
+    return { ok: false, message: `Target generation "${input.targetGeneration}" not found` };
+  } else {
+    const receipt = JSON.parse(new TextDecoder().decode(receiptBody));
+    head = {
+      schema: HEAD_MANIFEST_SCHEMA,
+      generation: receipt.generation,
+      manifestKey: receipt.rootKey,
+      manifestHash: receipt.rootHash,
+      publishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      previousGeneration: current.head.generation,
+      trust: current.head.trust ?? "trusted-origin",
+      revision: (current.head.revision ?? 1) + 1,
+      layout: "incremental-cas"
+    };
+  }
+  const fenced = input.safety.mode !== "unfenced";
+  const etag = input.expectedHeadEtag ?? current.headEtag;
+  const committed = await commitHead(state, head, input.safety, fenced, etag);
+  if ("conflict" in committed) {
+    return { ok: false, message: committed.conflict.message };
+  }
+  return {
+    ok: true,
+    head,
+    ...committed.etag !== void 0 && { headEtag: committed.etag }
+  };
+}
+
+// src/publication/gc.ts
+var PROTECTED_KEYS = /* @__PURE__ */ new Set([HEAD_KEY, STATUS_KEY, PINS_KEY]);
+function generationFromKey(key) {
+  if (key.startsWith(`${GENERATIONS_PREFIX}/`)) {
+    return key.split("/", 2)[1];
+  }
+  if (key.startsWith(`${RECEIPTS_PREFIX}/`) && key.endsWith(".json")) {
+    return key.slice(RECEIPTS_PREFIX.length + 1, -".json".length);
+  }
+  return void 0;
+}
+async function collectGenerationKeys(store, generation) {
+  const keys = [];
+  for await (const key of store.listAsync(`${GENERATIONS_PREFIX}/${generation}/`)) {
+    keys.push(key);
+  }
+  const receipt = `${RECEIPTS_PREFIX}/${generation}.json`;
+  if (await store.stat(receipt) !== void 0) keys.push(receipt);
+  return keys;
+}
+async function collectCasAndMapFromHead(state, index, generation) {
+  const stateKeys = [];
+  const indexKeys = [];
+  stateKeys.push(...await collectGenerationKeys(state, generation));
+  if (index !== void 0) {
+    for await (const key of index.listAsync(`${GENERATIONS_PREFIX}/${generation}/`)) {
+      indexKeys.push(key);
+    }
+  }
+  const receiptKey = `${RECEIPTS_PREFIX}/${generation}.json`;
+  const receiptBody = await state.get(receiptKey);
+  if (receiptBody === void 0) {
+    return { stateKeys, indexKeys };
+  }
+  stateKeys.push(receiptKey);
+  const receipt = JSON.parse(new TextDecoder().decode(receiptBody));
+  if (receipt.rootKey !== void 0) stateKeys.push(receipt.rootKey);
+  if (receipt.rootHash !== void 0) {
+    const rootKey = receipt.rootKey ?? `${MAP_ROOTS_PREFIX}/${receipt.rootHash}.json`;
+    const rootBody = await state.get(rootKey);
+    if (rootBody !== void 0) {
+      const root = JSON.parse(new TextDecoder().decode(rootBody));
+      for (const shardHash of Object.values(root.shards ?? {})) {
+        const shardKey = `${MAP_SHARDS_PREFIX}/${shardHash}.json`;
+        stateKeys.push(shardKey);
+        const shardBody = await state.get(shardKey) ?? (index === void 0 ? void 0 : await index.get(shardKey));
+        if (shardBody === void 0) continue;
+        const shard = JSON.parse(new TextDecoder().decode(shardBody));
+        for (const entry of Object.values(shard.entries ?? {})) {
+          const casKey = `${CAS_PREFIX}/${entry.hash}`;
+          indexKeys.push(casKey);
+          stateKeys.push(casKey);
+        }
+      }
+    }
+  }
+  for (const obj of receipt.objects ?? []) {
+    if (obj.role === "index") indexKeys.push(obj.key);
+    else stateKeys.push(obj.key);
+  }
+  return { stateKeys, indexKeys };
+}
+async function planGarbageCollection(options) {
+  const {
+    state,
+    index,
+    policy,
+    inFlightGeneration
+  } = options;
+  if (policy.mode === "forever") {
+    return {
+      policy,
+      deleteKeys: [],
+      retainKeys: []
+    };
+  }
+  const head = await readPublishedHead(state);
+  const pins = await listPins(state);
+  const protectedGens = /* @__PURE__ */ new Set();
+  if (head !== void 0) protectedGens.add(head.head.generation);
+  if (head?.head.previousGeneration !== void 0) {
+    protectedGens.add(head.head.previousGeneration);
+  }
+  for (const pin of pins) protectedGens.add(pin.generation);
+  if (inFlightGeneration !== void 0) protectedGens.add(inFlightGeneration);
+  const allGenKeys = await state.list(`${GENERATIONS_PREFIX}/`);
+  const genIds = /* @__PURE__ */ new Set();
+  for (const key of allGenKeys) {
+    const id = generationFromKey(key);
+    if (id !== void 0) genIds.add(id);
+  }
+  for await (const key of state.listAsync(`${RECEIPTS_PREFIX}/`)) {
+    const id = generationFromKey(key);
+    if (id !== void 0) genIds.add(id);
+  }
+  const ordered = [...genIds].sort();
+  const retainTail = ordered.slice(-policy.retainGenerations);
+  for (const id of retainTail) protectedGens.add(id);
+  const liveState = new Set(PROTECTED_KEYS);
+  const liveIndex = /* @__PURE__ */ new Set();
+  for (const gen of protectedGens) {
+    const collected = await collectCasAndMapFromHead(state, index, gen);
+    for (const k of collected.stateKeys) liveState.add(k);
+    for (const k of collected.indexKeys) liveIndex.add(k);
+  }
+  const deleteKeys = [];
+  const retainKeys = [];
+  for await (const key of state.listAsync()) {
+    if (PROTECTED_KEYS.has(key)) {
+      retainKeys.push({
+        role: "state",
+        key,
+        reason: "protected-well-known"
+      });
+      continue;
+    }
+    if (liveState.has(key)) {
+      retainKeys.push({
+        role: "state",
+        key,
+        reason: "live"
+      });
+      continue;
+    }
+    const gen = generationFromKey(key);
+    if (gen !== void 0 && protectedGens.has(gen)) {
+      retainKeys.push({
+        role: "state",
+        key,
+        reason: "protected-generation"
+      });
+      continue;
+    }
+    deleteKeys.push({
+      role: "state",
+      key,
+      reason: "unreferenced"
+    });
+  }
+  if (index !== void 0) {
+    for await (const key of index.listAsync()) {
+      if (liveIndex.has(key)) {
+        retainKeys.push({
+          role: "index",
+          key,
+          reason: "live"
+        });
+        continue;
+      }
+      const gen = generationFromKey(key);
+      if (gen !== void 0 && protectedGens.has(gen)) {
+        retainKeys.push({
+          role: "index",
+          key,
+          reason: "protected-generation"
+        });
+        continue;
+      }
+      deleteKeys.push({
+        role: "index",
+        key,
+        reason: "unreferenced"
+      });
+    }
+  }
+  void policy.cdnGraceMs;
+  return {
+    policy,
+    deleteKeys,
+    retainKeys
+  };
+}
+async function runGarbageCollection(plan, stores, opts) {
+  const dryRun = opts?.dryRun !== false;
+  const deleted = [];
+  const skipped = [];
+  if (dryRun) {
+    return {
+      dryRun: true,
+      deleted: [],
+      skipped: plan.deleteKeys
+    };
+  }
+  for (const ref of plan.deleteKeys) {
+    try {
+      const store = ref.role === "index" ? stores.index : stores.state;
+      if (store === void 0) {
+        skipped.push({ ...ref, reason: "no-store" });
+        continue;
+      }
+      await store.delete(ref.key);
+      deleted.push(ref);
+    } catch {
+      skipped.push(ref);
     }
+  }
+  return {
+    dryRun: false,
+    deleted,
+    skipped
+  };
+}
+
+// src/publication/incremental.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+
+// src/publication/shard.ts
+function shardIdForKey(logicalKey, hexChars = DEFAULT_SHARD_HEX_CHARS) {
+  let h = 2166136261;
+  for (let i = 0; i < logicalKey.length; i++) {
+    h ^= logicalKey.codePointAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0").slice(0, hexChars);
+}
+
+// src/publication/incremental.ts
+function toBytes3(body) {
+  return typeof body === "string" ? new TextEncoder().encode(body) : body;
+}
+async function putCas(store, body, contentType, fenced) {
+  const hash = hashBytes(body);
+  const key = `${CAS_PREFIX}/${hash}`;
+  const opts = {
+    contentType,
+    cacheControl: CACHE_CONTROL_IMMUTABLE
+  };
+  if (fenced) {
+    await putCreateOnly(store, key, body, opts);
+  } else {
+    const existing = await store.get(key);
+    if (existing === void 0) await store.put(key, body, opts);
+  }
+  return { hash, key };
+}
+async function loadRoot(state, head) {
+  if (head === void 0 || head.layout !== "incremental-cas") {
+    return { schema: MAP_ROOT_SCHEMA, shards: {} };
+  }
+  const body = await state.get(head.manifestKey);
+  if (body === void 0) {
+    return { schema: MAP_ROOT_SCHEMA, shards: {} };
+  }
+  return JSON.parse(new TextDecoder().decode(body));
+}
+async function loadShard(state, shardHash) {
+  if (shardHash === void 0) {
+    return { schema: MAP_SHARD_SCHEMA, entries: {} };
+  }
+  const key = `${MAP_SHARDS_PREFIX}/${shardHash}.json`;
+  const body = await state.get(key);
+  if (body === void 0) {
+    return { schema: MAP_SHARD_SCHEMA, entries: {} };
+  }
+  return JSON.parse(new TextDecoder().decode(body));
+}
+async function publishIncremental(input) {
+  const generation = input.generation ?? randomUUID2();
+  const fenced = input.safety.mode !== "unfenced";
+  const hexChars = input.shardHexChars ?? DEFAULT_SHARD_HEX_CHARS;
+  let writes = 0;
+  if (input.assertSafety !== false && input.safety.mode === "conditional-head") {
+    await assertPublicationSafety(input.state, input.safety);
+  }
+  const prior = await readPublishedHead(input.state);
+  const root = await loadRoot(input.state, prior?.head);
+  const touched = /* @__PURE__ */ new Map();
+  const applyChange = async (store, object) => {
+    const logicalKey = object.key.replaceAll(/^\/+/g, "");
+    const bytes = toBytes3(object.body);
+    const contentType = object.contentType ?? "application/json";
+    const cas = await putCas(store, bytes, contentType, fenced);
+    writes += 1;
+    const sid = shardIdForKey(logicalKey, hexChars);
+    let shard = touched.get(sid);
+    if (shard === void 0) {
+      shard = await loadShard(input.state, root.shards[sid]);
+      touched.set(sid, shard);
+    }
+    shard.entries[logicalKey] = {
+      hash: cas.hash,
+      size: bytes.byteLength,
+      contentType
+    };
+  };
+  for (const object of input.indexChanges ?? []) {
+    await applyChange(input.index, object);
+  }
+  for (const object of input.stateChanges ?? []) {
+    await applyChange(input.state, object);
+  }
+  for (const logicalKey of input.deletedKeys ?? []) {
+    const sid = shardIdForKey(logicalKey, hexChars);
+    let shard = touched.get(sid);
+    if (shard === void 0) {
+      shard = await loadShard(input.state, root.shards[sid]);
+      touched.set(sid, shard);
+    }
+    delete shard.entries[logicalKey];
+  }
+  const nextShards = { ...root.shards };
+  for (const [sid, shard] of touched) {
+    const shardBody = `${JSON.stringify(shard, null, 2)}
+`;
+    const shardHash = hashBytes(shardBody);
+    const shardKey = `${MAP_SHARDS_PREFIX}/${shardHash}.json`;
+    if (fenced) {
+      await putCreateOnly(input.state, shardKey, shardBody, {
+        contentType: "application/json",
+        cacheControl: CACHE_CONTROL_IMMUTABLE
+      });
+    } else {
+      await input.state.put(shardKey, shardBody, {
+        contentType: "application/json",
+        cacheControl: CACHE_CONTROL_IMMUTABLE
+      });
+    }
+    writes += 1;
+    if (Object.keys(shard.entries).length === 0) delete nextShards[sid];
+    else nextShards[sid] = shardHash;
+  }
+  const nextRoot = { schema: MAP_ROOT_SCHEMA, shards: nextShards };
+  const rootBody = `${JSON.stringify(nextRoot, null, 2)}
+`;
+  const rootHash = hashBytes(rootBody);
+  const rootKey = `${MAP_ROOTS_PREFIX}/${rootHash}.json`;
+  if (fenced) {
+    await putCreateOnly(input.state, rootKey, rootBody, {
+      contentType: "application/json",
+      cacheControl: CACHE_CONTROL_IMMUTABLE
+    });
+  } else {
+    await input.state.put(rootKey, rootBody, {
+      contentType: "application/json",
+      cacheControl: CACHE_CONTROL_IMMUTABLE
+    });
+  }
+  writes += 1;
+  const publishedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const receipt = {
+    schema: RECEIPT_SCHEMA,
+    generation,
+    publishedAt,
+    rootHash,
+    rootKey,
+    changedCount: (input.indexChanges?.length ?? 0) + (input.stateChanges?.length ?? 0) + (input.deletedKeys?.length ?? 0),
+    reducer: {
+      name: input.reducer.name,
+      ...input.reducer.version !== void 0 && { version: input.reducer.version }
+    },
+    ...input.previousGeneration !== void 0 && { previousGeneration: input.previousGeneration },
+    ...prior?.head.generation !== void 0 && input.previousGeneration === void 0 && { previousGeneration: prior.head.generation },
+    ...input.source !== void 0 && { source: input.source }
+  };
+  const receiptBody = `${JSON.stringify(receipt, null, 2)}
+`;
+  const receiptKey = `${RECEIPTS_PREFIX}/${generation}.json`;
+  if (fenced) {
+    await putCreateOnly(input.state, receiptKey, receiptBody, {
+      contentType: "application/json",
+      cacheControl: CACHE_CONTROL_IMMUTABLE
+    });
+  } else {
+    await input.state.put(receiptKey, receiptBody, {
+      contentType: "application/json",
+      cacheControl: CACHE_CONTROL_IMMUTABLE
+    });
+  }
+  writes += 1;
+  const trustMode = input.trust?.mode ?? "trusted-origin";
+  const head = {
+    schema: HEAD_MANIFEST_SCHEMA,
+    generation,
+    layout: "incremental-cas",
+    manifestKey: rootKey,
+    manifestHash: rootHash,
+    publishedAt,
+    trust: trustMode,
+    ...receipt.previousGeneration !== void 0 && { previousGeneration: receipt.previousGeneration },
+    revision: input.revision ?? (prior?.head.revision ?? 0) + 1
+  };
+  if (input.trust?.mode === "signed") {
+    head.signature = await input.trust.sign(canonicalHeadBytes(head));
+  }
+  const committed = await commitHead(
+    input.state,
+    head,
+    input.safety,
+    fenced,
+    input.expectedHeadEtag ?? prior?.headEtag
+  );
+  if ("conflict" in committed) {
+    return {
+      ok: false,
+      conflict: {
+        kind: committed.conflict.kind,
+        message: committed.conflict.message
+      }
+    };
+  }
+  void CACHE_CONTROL_REVALIDATE;
+  void HEAD_KEY;
+  return {
+    ok: true,
+    generation,
+    head,
+    receipt,
+    root: nextRoot,
+    rootHash,
+    writes,
+    ...committed.etag !== void 0 && { headEtag: committed.etag }
   };
 }
 
@@ -306,13 +1921,60 @@ var noopReducer = {
 };
 export {
   AbstractActor,
+  CACHE_CONTROL_IMMUTABLE,
+  CACHE_CONTROL_REVALIDATE,
+  CAS_PREFIX,
+  ConditionalWriteError,
+  DAPP_STORE_ROLES,
+  DEFAULT_SHARD_HEX_CHARS,
   DappActor,
   DappDataStoreMoniker,
   DappIndexStoreMoniker,
   DappStateStoreMoniker,
+  GENERATIONS_PREFIX,
+  GENERATION_MANIFEST_SCHEMA,
+  HEAD_KEY,
+  HEAD_MANIFEST_SCHEMA,
+  INDEXER_STATUS_SCHEMA,
+  MAP_ROOTS_PREFIX,
+  MAP_ROOT_SCHEMA,
+  MAP_SHARDS_PREFIX,
+  MAP_SHARD_SCHEMA,
+  PINS_KEY,
+  PINS_SCHEMA,
+  RECEIPTS_PREFIX,
+  RECEIPT_SCHEMA,
+  ReadOnlyStoreError,
+  STATUS_KEY,
+  asReadOnly,
+  asReadOnlyWriter,
+  assertPublicationSafety,
   bootDappActors,
+  canonicalHeadBytes,
   createDappLocator,
+  createMemoryBucketStore,
   createS3BucketStore,
-  noopReducer
+  hashBytes,
+  isConditionalWriteError,
+  joinKey,
+  listPins,
+  listReleases,
+  noopReducer,
+  normalizePublicBaseUrl,
+  pinRelease,
+  planGarbageCollection,
+  probePublicationCapabilities,
+  publishGeneration,
+  publishIncremental,
+  putCreateOnly,
+  readIndexerStatus,
+  readPublishedHead,
+  resolveS3Client,
+  rollbackHead,
+  runGarbageCollection,
+  shardIdForKey,
+  stripPrefix,
+  unpinRelease,
+  writeIndexerStatus
 };
 //# sourceMappingURL=index.mjs.map