@fairfox/polly 0.71.0 → 0.73.0

package/dist/src/shared/lib/sweep-sealed.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `sweepSealed` — storage-adapter garbage collection of sealed mesh-doc
+ * bytes (polly#121).
+ *
+ * When a consumer compacts a `$meshState` document it seeds a fresh
+ * successor and leaves an in-band sentinel in the old document. polly's
+ * {@link RedirectDetector} follows that sentinel so live wrappers rebind
+ * transparently — but the old document's bytes then sit in storage
+ * forever, because nothing removes them.
+ *
+ * `sweepSealed` is that missing GC step. polly owns the walk, the
+ * open-handle gate, the age window, the dry-run report and the byte
+ * removal. The consumer owns the sentinel shape — it is the very
+ * document the consumer's {@link RedirectDetector} already inspects —
+ * supplied here as the {@link SweepSealedOptions.isSealed} predicate.
+ * polly deliberately does not define a canonical sentinel format: that
+ * would compete with the one consumers' detectors already read.
+ *
+ * polly never runs this on a timer. The consumer calls it explicitly.
+ *
+ * ## Redirect-index-not-yet-synced hazard
+ *
+ * A peer whose redirect index (`mesh:document-index`) has not yet synced
+ * may still reach for a sealed document by its *old* docId. If the sweep
+ * has just removed that document's bytes, the peer gets a
+ * missing-document error instead of a redirect. Two gates bound the risk,
+ * and the caller must size them deliberately:
+ *
+ *  - `olderThan` — only documents sealed longer ago than this window are
+ *    swept. Make it comfortably larger than the worst-case time a peer
+ *    can stay offline-then-resync, so any peer that could still hold the
+ *    old docId has had the redirect delivered.
+ *  - the open-handle gate — a document with a live handle on the supplied
+ *    `repo` is never swept, regardless of age.
+ *
+ * Neither gate can see a peer that is currently offline; `olderThan` is
+ * the only protection there. Choose it conservatively.
+ */
+import type { DocumentId, Repo, StorageAdapterInterface } from "@automerge/automerge-repo/slim";
+export interface SweepSealedOptions {
+    /** The Repo whose storage is swept. Its open handles gate removal. */
+    repo: Repo;
+    /** The storage adapter backing {@link repo}. */
+    storage: StorageAdapterInterface;
+    /**
+     * Predicate that recognises a sealed document. Given a materialised
+     * document, returns the epoch-ms timestamp at which it was sealed, or
+     * `undefined` if the document is not sealed.
+     *
+     * This is the same document the consumer's {@link RedirectDetector}
+     * inspects: the consumer owns the sentinel shape, polly never defines
+     * it. The returned timestamp feeds both the {@link olderThan} filter
+     * and the dry-run report.
+     */
+    isSealed: (doc: unknown) => number | undefined;
+    /** Sweep only documents sealed more than this many milliseconds ago. */
+    olderThan: number;
+    /**
+     * The candidate documents to consider. When omitted, the sweep
+     * enumerates the whole adapter via `storage.loadRange([])`.
+     *
+     * That whole-adapter enumeration works for the IndexedDB and
+     * in-memory adapters but **not** the NodeFS adapter, whose `loadRange`
+     * requires at least a documentId prefix. Server-side callers should
+     * use {@link PeerRepoServer.sweepSealed}, which enumerates the
+     * filesystem and supplies this list; per-document `loadRange` then
+     * works on every adapter.
+     */
+    documentIds?: Iterable<string>;
+    /** When true, report candidates without removing anything. */
+    dryRun?: boolean;
+    /** Clock source, injectable for tests. Defaults to {@link Date.now}. */
+    now?: () => number;
+}
+/** A document removed by the sweep — or, under `dryRun`, that would be. */
+export interface SweptDoc {
+    documentId: DocumentId;
+    /** Epoch-ms the document was sealed, as reported by `isSealed`. */
+    sealedAt: number;
+    /** Total bytes across the document's storage chunks. */
+    byteSize: number;
+}
+/** Why a sealed document was left in place rather than swept. */
+export type KeptReason = "open-handle" | "too-recent";
+/** A sealed document the sweep deliberately did not remove. */
+export interface KeptDoc {
+    documentId: DocumentId;
+    reason: KeptReason;
+}
+export interface SweepResult {
+    /** Documents removed — or, under `dryRun`, that would be removed. */
+    swept: SweptDoc[];
+    /** Sealed documents deliberately left in place, with the reason. */
+    kept: KeptDoc[];
+    /** Echoes the `dryRun` flag the sweep ran under. */
+    dryRun: boolean;
+}
+/**
+ * Garbage-collect sealed mesh-doc bytes from a Repo's storage adapter.
+ *
+ * Walks every candidate document, materialises it, and asks
+ * {@link SweepSealedOptions.isSealed} whether it is sealed. A sealed
+ * document is removed only when it has no open handle on the Repo *and*
+ * was sealed longer ago than `olderThan`; otherwise it is reported under
+ * `kept` with the reason. Unsealed documents are never touched and never
+ * reported. With `dryRun`, candidates are reported but nothing is removed.
+ *
+ * See the module doc comment for the redirect-index-not-yet-synced
+ * hazard that `olderThan` and the open-handle gate exist to bound.
+ */
+export declare function sweepSealed(options: SweepSealedOptions): Promise<SweepResult>;

package/dist/tools/quality/src/cli.js

@@ -33,7 +33,11 @@ var DEFAULT_SHARED_COMPONENT_RULES = [
     element: "<textarea>",
     replacement: '<ActionInput variant="multi">'
   },
-  { pattern: /<select[\s>]/, element: "<select>", replacement: "<Select>" },
+  {
+    pattern: /<select[\s>]/,
+    element: "<select>",
+    replacement: "<Select> or <ActionSelect>"
+  },
   { pattern: /<form[\s>]/, element: "<form>", replacement: "<ActionForm>" },
   { pattern: /<dialog[\s>]/, element: "<dialog>", replacement: "<Modal>" }
 ];
@@ -3046,4 +3050,4 @@ switch (subcommand) {
 }
 process.exit(exitCode);
 
-//# debugId=C337428BF011F4B264756E2164756E21
+//# debugId=BE14883E9B3EB87B64756E2164756E21