@bazariodev/docket 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,986 @@
-# Temporary Holding Version
+# @bazariodev/docket
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Record structured diagnostic data. Remove private values before delivery, keep bounded history,
+and build ZIP files for download or application upload.
+
+## Install
+
+```sh
+pnpm add @bazariodev/docket
+```
+
+Docket uses [Coordination](https://www.npmjs.com/package/@bazariodev/coordination) as a runtime
+dependency. The `/history` entry creates its private `Queue` directly. The root entry has no
+external runtime imports. Public declarations use local types and structural provider ports.
+Memory history, upload, conversion, persistence, SIP, and ZIP support are optional entries.
+Import only the entries that the application uses.
+
+The usage example selects [Winnow](https://www.npmjs.com/package/@bazariodev/winnow) for bounded
+conversion:
+
+```sh
+pnpm add @bazariodev/winnow
+```
+
+Other providers can implement the same structural ports. A selected provider can install its own
+dependencies. Docket does not change that provider's package graph. Optional examples below also
+select [Baler](https://www.npmjs.com/package/@bazariodev/baler) for ZIP files and
+[Hopper](https://www.npmjs.com/package/@bazariodev/hopper) for standalone persistence.
+Install these packages only for the corresponding application composition.
+
+Node.js support is `^22.12.0 || ^24.0.0 || >=26.0.0`. Browser persistence needs the selected storage
+provider's platform APIs. The Hopper IndexedDB composition uses IndexedDB and Web Locks.
+Memory history and memory outboxes use no device storage or application lease.
+
+## Usage
+
+```js
+import { createDocket } from '@bazariodev/docket/client';
+import { createRedactor } from '@bazariodev/docket/redaction';
+import * as conversion from '@bazariodev/winnow';
+
+const redactor = createRedactor(
+  { fields: { password: 'drop', accessToken: 'drop' } },
+  conversion,
+);
+const docket = createDocket({
+  areas: [{ id: 'application' }, { id: 'network', level: 'warn' }],
+  redactor,
+});
+docket.getLogger('application', 'Connection').info('Connection ready');
+const records = await docket.history?.query();
+```
+
+This call keeps the last 1,000 records in memory. Console output and upload are off.
+It uses no device storage.
+Supply your application's area list and privacy policy. Default text rules do not identify every
+private field in an application.
+
+| Task | Example or guidance |
+| --- | --- |
+| Keep and query local history | [Memory history](#memory-history). |
+| Add console output or a custom sink | [Console output and custom sinks](#console-output-and-custom-sinks). |
+| Keep history and upload independently | [Storage and delivery options](#storage-and-delivery-options). |
+| Add correlation context, Errors, or lazy data | [Context, Errors, and lazy data](#context-errors-and-lazy-data). |
+| Produce JSON or NDJSON | [JSON and NDJSON](#json-and-ndjson). |
+| Select capacity and bound input cost | [Capacity and input cost](#capacity-and-input-cost). |
+| Flush, stop, erase, and remove browser listeners | [Shutdown and account changes](#shutdown-and-account-changes). |
+
+## Storage and delivery options
+
+History and upload are independent. No strategy name or storage registry is required.
+
+| Options | Result |
+| --- | --- |
+| Neither option | Cyclic memory history; no upload. |
+| `history: { maxRecords: 2000 }` | Cyclic memory history with another capacity. |
+| `history: historyClient` | Use a supplied memory, IndexedDB, or other compatible client. |
+| `history: false`, `upload: { ... }` | Upload only. |
+| `history: { ... }`, `upload: { ... }` | History and upload. |
+| `upload: false` or omitted upload | No upload. |
+
+Supply Hopper clients directly, or supply other clients with the same public methods.
+Open persistent clients only after authentication. The application supplies an opaque
+`authenticatedSession.storageKey` and an `uploadRecords` callback bound to that same account.
+Use a different scope for each tenant and account:
+
+```js
+import { createIndexedDbStore } from '@bazariodev/hopper/indexeddb';
+import { createIndexedDbOutbox } from '@bazariodev/hopper/outbox/indexeddb';
+
+const scope = authenticatedSession.storageKey;
+const names = (kind) => ({
+  databaseName: JSON.stringify(['diagnostics', scope, kind]),
+  lockName: JSON.stringify(['diagnostics-owner', scope, kind]),
+});
+const storageOptions = { history: names('history'), outbox: names('outbox') };
+const historyClient = createIndexedDbStore(storageOptions.history);
+const outbox = await createIndexedDbOutbox({
+  ...storageOptions.outbox,
+  maxRecords: 1000,
+});
+const persistent = createDocket({
+  areas: [{ id: 'application' }],
+  redactor,
+  history: historyClient,
+  upload: {
+    outbox,
+    send: uploadRecords,
+  },
+});
+```
+
+The client selects storage. Docket imports no Hopper code. For memory upload, supply
+`createMemoryOutbox({ maxRecords })` from `@bazariodev/hopper/outbox`. The outbox is required;
+its factory owns capacity and storage configuration. Docket does not copy those options.
+
+A history client needs `write`, `query`, and `clear`; `flush`, `stop`, and `getStatus` are optional.
+An outbox needs the public upload port plus `clear` and `stop`. Methods keep their receivers.
+The returned `history` and `outbox` are the supplied clients. Do not use one client for both
+roles or share owned clients between compositions. A successful `createDocket` call owns their
+shutdown. Failed construction leaves supplied clients open and cancels its new upload timer.
+
+History keeps records for download. The outbox keeps records until server acceptance. They are
+separate stores: upload success must not erase local history. Clearing history must not remove
+pending upload records. Current Hopper history and outbox schemas need separate databases.
+Database and lock names come from initial client options. Use the same lock name for all writers
+of one database. Hopper history keeps its timestamp-order and identity rules; the default cyclic
+history keeps FIFO order and duplicate admissions.
+
+Upload defaults to 100 records per batch and a 5,000 ms interval. Supply
+`send(records, signal, token)`. The consumer owns the endpoint, credentials, encoding,
+request timeout, retry, response checks, and transport error reporting. Docket contains no HTTP client.
+
+Resolve the callback only after the backend accepts the complete batch. After handling a failure,
+throw or reject so Docket retains the batch and token. Catching an error and resolving reports
+success and permits acknowledgement. For example, the application can supply its API client
+and error reporter:
+
+```js
+async function uploadRecords(records, signal, token) {
+  try {
+    await api.uploadLogsWithRetry({ records, token }, { signal });
+  } catch (error) {
+    reportUploadError(error);
+    throw error;
+  }
+}
+```
+
+The application supplies `api.uploadLogsWithRetry` and `reportUploadError`. It must make API resolution mean complete
+acceptance. The backend must deduplicate the batch token in the application scope. A lost response
+or acknowledgement can cause a retry. Docket owns batching, one active callback, scheduling,
+retained batch protection, and acknowledgement. The callback must observe its abort signal.
+Supply a finite request timeout in the callback when required.
+
+`onError` is optional. Use it to observe storage or processor failures. If the callback reports
+transport errors itself, avoid reporting them again through this observer. Manual flush rejects
+on failure. A rejected callback retains the batch and pauses automatic attempts. New writes do not
+resume them. Call `flush()` explicitly to resume. Transport backoff stays inside the consumer callback.
+
+### Resume a paused upload
+
+For background upload, supply `upload.onError` or check `getStatus().paused` in the application's
+status updates. Otherwise a rejected callback can leave upload paused without an application
+notification. Writes continue during a pause. At capacity, the outbox evicts old unprotected
+records or drops incoming records when the protected batch fills capacity. Check `droppedRecords`.
+Resuming does not restore records lost to capacity.
+
+Any explicit processor or hub flush resumes upload. This includes `docket.flush()` and a call
+made by `flushOnPageHide(docket)`. Docket installs no page-exit listener itself. To flush only
+local history on page exit, pass `{ flush: () => historyClient.flush() }` to that helper instead.
+Keep offline, call-state, and transport retry gates inside the consumer's send callback. A pending
+callback must observe its abort signal; a rejected callback pauses automatic attempts.
+
+The consumer can retry after an explicit user action or a connectivity event. This example uses
+the application's `redactor`, `outbox`, `uploadRecords`, `refreshUploadStatus`, and retry button.
+The status helper updates the interface; the send callback reports transport errors:
+
+```js
+const docket = createDocket({
+  areas: [{ id: 'application' }],
+  redactor,
+  upload: {
+    outbox,
+    send: uploadRecords,
+    onError: refreshUploadStatus,
+  },
+});
+const listenerLifetime = new AbortController();
+
+async function resumeUpload() {
+  const upload = docket.upload;
+  const status = upload?.getStatus();
+  if (!status?.paused || status.stopped) return;
+  try {
+    await upload.flush();
+  } catch {
+    // The upload observer updates the interface. Keep the batch paused.
+  }
+}
+
+const resume = () => void resumeUpload();
+const listenerOptions = { signal: listenerLifetime.signal };
+retryButton.addEventListener('click', resume, listenerOptions);
+window.addEventListener('online', resume, listenerOptions);
+
+async function stopDocket() {
+  listenerLifetime.abort();
+  await docket.stop();
+}
+```
+
+The `online` event is a retry trigger, not proof that the backend is available. Another rejection
+keeps the batch paused. The consumer can call the same resume function from its own backoff
+scheduler. Run it after the error observer returns; a synchronous flush inside that observer
+joins the failed operation. Keep resume work bound to the same account. Remove listeners and
+cancel consumer retry timers before account replacement or terminal shutdown.
+
+Call `await docket.flush()` for delivery. `docket.stop()` closes admission and cancels upload
+before it flushes and stops history and other sinks. It then stops the outbox, including after
+another cleanup step fails. Stop makes no final request and preserves persistent pending records.
+It is terminal and idempotent. Default memory history remains readable after stop.
+
+For logout, first close application admission, for example through `isActive`. Then stop the
+uploader, clear the outbox, stop the composition, and clear history:
+
+This flow intentionally discards pending records. If policy requires delivery first, await the
+old account's upload flush before stop, with its original credentials. On failure, retain the
+batch or report an explicit discard. Stop itself makes no final request.
+
+```js
+const failures = [];
+for (const step of [
+  () => persistent.resetLevel(),
+  () => persistent.upload.stop(),
+  () => persistent.outbox.clear(),
+  () => persistent.stop(),
+  () => persistent.history.clear(),
+]) {
+  try {
+    await step();
+  } catch (error) {
+    failures.push(error);
+  }
+}
+if (failures.length) throw new AggregateError(failures, 'Cleanup failed');
+```
+
+Hopper outbox clear requires an active adapter. Do not clear it after outbox stop.
+The application owns account changes and credentials. No account controller or automatic disk
+cleanup is added.
+
+After a crash or forced sign-out, the next account must use its own resource names. Do not open
+an old account's outbox with a new account's sender. Keep the old names if cleanup needs retry.
+When no old client holds the locks, use Hopper `clearIndexedDbStore(storageOptions.history)` and
+`clearIndexedDbOutbox(storageOptions.outbox)`. Both clear existing storage without creating a
+database. Use the outbox helper for outboxes; history cleanup removes different metadata.
+
+## Low-level composition
+
+Use `createLogging` when the application already owns its sinks and shutdown order:
+
+```js
+import { createLogging } from '@bazariodev/docket';
+import { createMemoryHistory } from '@bazariodev/docket/history';
+
+const history = createMemoryHistory({ maxRecords: 1000 });
+const logging = createLogging({
+  areas: [{ id: 'application' }, { id: 'network', level: 'warn' }],
+  redactor,
+  sinks: [history],
+});
+```
+
+The later examples reuse `conversion`, `redactor`, `history`, and `logging` from these examples.
+Each memory history owns a separate Coordination queue. The application supplies no queue factory.
+
+### Console output and custom sinks
+
+Console output requires an explicit sink. This example adds it to the hub above:
+
+```js
+import { createConsoleSink } from '@bazariodev/docket';
+
+const detachConsole = logging.addSink(createConsoleSink({ level: 'info' }));
+```
+
+A custom sink receives redacted, frozen records. Its `write(record)` must complete admission
+synchronously. The hub ignores its return value. It does not track returned promises, wait for
+them during flush, or contain their asynchronous rejections. For example:
+
+```js
+const detachOutput = logging.addSink({
+  write(record) {
+    output(record);
+  },
+});
+```
+
+The application supplies the synchronous `output` function. Use
+[the upload sink](#periodic-upload) and its `send` callback for backend delivery.
+A custom asynchronous destination must own its bounded buffer and failure handling.
+Its optional `flush()` must wait for work admitted before that call. Its optional `stop()`
+must release its resources. The hub awaits these lifecycle methods.
+
+Call `detachOutput()` or `detachConsole()` to stop future delivery to that registration.
+Detach does not flush or stop the sink. The application must complete its cleanup separately.
+
+### Page-lifetime loggers and account sinks
+
+Keep one root hub when modules cache their loggers for the whole page. Stop is terminal;
+cached loggers from a stopped hub ignore later writes. Creating a new account client cannot
+redirect those loggers. Use the same page hub and replace its account sinks instead:
+
+```js
+const logging = createLogging({
+  areas: [{ id: 'application' }],
+  redactor,
+  isActive: () => accountActive,
+});
+const logger = logging.getLogger('application', 'Connection');
+const detachHistory = logging.addSink(accountHistory);
+const detachUpload = logging.addSink(accountUpload);
+```
+
+The application supplies the gate and both account sinks. Close admission before an account
+change. Reset levels while the hub is active, detach old sinks, then stop and erase those old
+clients. Attach new sinks before opening admission. Do not call hub stop at account boundaries.
+The hub keeps one `runId` and increasing sequence numbers across accounts. `copyRecords` can
+copy a pre-account source when application policy permits it; attaching a sink copies no backlog.
+
+### Level overrides
+
+`levelStorage` is optional. Without it, overrides live only in the hub. Supply a distinct key
+for each tenant, account, and hub. For example, use
+`JSON.stringify(['diagnostic-levels', accountStorageKey, hubId])` with the application's storage.
+Do not share one key between hubs or reuse an old account's key for another account.
+Saving replaces that key with this hub's active overrides; it does not merge other areas.
+
+Call `resetLevel()` before stop for logout. Reset after stop does nothing. For a page-lifetime
+hub, reset before account replacement, select the new account's storage, then call `reloadLevels()`.
+Use a stable storage port that routes operations to the current account key. Replacing the
+constructor option does not replace the hub's captured port.
+The application owns storage permission, cross-tab notifications, and removal of old keys.
+Expiry uses wall-clock timestamps. A backward clock adjustment can extend elapsed duration;
+`maxOverrideMs` does not promise a monotonic elapsed-time deadline.
+
+### Context, Errors, and lazy data
+
+Keep scope names stable. Put variable correlation IDs in child context:
+
+```js
+const log = logging.getLogger('application', 'Request');
+const requestLog = log.child({ context: { requestId: 'request-123' } });
+requestLog.error('Request failed', new Error('Timed out'));
+requestLog.debug('Request counters', () => readRequestCounters());
+```
+
+The application supplies the synchronous `readRequestCounters` function. Docket calls it only
+after the initial admission checks. Later state changes or record validation can still discard
+the record. Select a few diagnostic fields; do not return the whole application store.
+The redactor still applies the application's privacy policy to context, Errors, and lazy data.
+
+## Consumer redaction policy
+
+The application selects which values to keep, remove, mask, or hash. Redaction is the complete
+process; masking and hashing are two possible actions. The package does not require hashing for
+core logging, SIP, storage, or export.
+
+```js
+import { createRedactor } from '@bazariodev/docket/redaction';
+
+const redactor = createRedactor({
+  fields: { password: 'drop', email: 'mask', state: 'keep' },
+  unknownFields: 'drop',
+}, conversion);
+```
+
+Field names match without case at every data depth, including context and Error properties.
+
+| Action | Result |
+| --- | --- |
+| `keep` | Keep the field and apply nested and text rules. This does not bypass text redaction. |
+| `drop` | Remove the field. |
+| `mask` | Hide part of the value. Short strings are hidden completely. Longer digit strings keep the last four digits; other strings keep the first and last character. |
+| `hash` | Replace the value with the result of the application's hash function. |
+
+Use `text` rules to replace selected text with a fixed value such as `[redacted]`, or to apply
+another application rule. Custom `policy.text` rules receive the Docket record API. An explicit
+`text` list replaces the default list. `text: []` disables text rules. Provider defaults belong in
+`conversion.TEXT_RULES`; their callbacks receive the value engine API. To select a provider subset,
+supply a dictionary such as `{ email: TEXT_RULES.email }` as `TEXT_RULES` and omit `policy.text`.
+Unknown fields default to `keep`; use `unknownFields: 'drop'` when only named fields are permitted.
+
+Storm summaries also use this field policy. To retain the `logging.suppressed` counts with
+`unknownFields: 'drop'`, allow `scope` and `dropped` with the `keep` action. Otherwise the policy
+can remove those summary fields.
+
+Field mask/hash actions convert numbers and bigint to text. Other non-string values use a fixed
+redaction marker without a hash call. Error schema field rules use the same actions. Captured runtime
+accessors supply Error stacks and DOMException fields. Runtime stack formatting can call an
+application `Error.prepareStackTrace` function.
+
+Hashing is optional. The application supplies the function and owns its algorithm and key.
+For example, the application can call this factory with its synchronous keyed hasher:
+
+```js
+import { createRedactor } from '@bazariodev/docket/redaction';
+
+export function createApplicationRedactor(hashPrivateValue, conversion) {
+  return createRedactor({
+    hash: hashPrivateValue,
+    fields: { customerId: 'hash', password: 'drop' },
+    unknownFields: 'drop',
+  }, conversion);
+}
+```
+
+Text-rule methods use the compiled rule as their receiver and receive the Docket redactor API.
+Docket captures the hash function at construction and calls it with the original policy as its receiver.
+Prototype hash methods are supported. Later changes to `policy.hash` do not replace the captured
+function; the captured method can still read current policy state.
+
+The hash function must return a string synchronously. A Promise is not supported. A hash rule
+without a function rejects policy creation. The package checks the output type and limits; it
+does not verify the algorithm's security. Keep secret keys out of records and exports. Keyed
+tokens can connect equal values under the same key; they do not encrypt the logs.
+
+An application can also supply its own `Redactor`. The hub still validates, copies, and freezes
+its output within the declared limits. These checks do not prove that a privacy policy removes
+all private data. Select the policy before recording. Export cannot restore removed values.
+
+## SIP display names
+
+```js
+import { createRedactor } from '@bazariodev/docket/redaction';
+import { createSipTools } from '@bazariodev/docket/sip';
+import { TEXT_RULES } from '@bazariodev/winnow';
+
+const { redactSipMessage } = createSipTools(TEXT_RULES);
+const redactor = createRedactor({}, conversion);
+const message = 'SIP/2.0 200 OK\r\nFrom: "Alice" <sip:alice@example.com>\r\n\r\n';
+const fixed = redactSipMessage(message, { redactor });
+const masked = redactSipMessage(message, {
+  redactor,
+  redactDisplayName: (value) => redactor.mask(value),
+});
+```
+
+The SIP factory needs five match-only rules: `ipv4`, `ipv6`, `urlCredentials`, `sipUri`, and
+`telUri`. Winnow supplies these rules directly. Other providers must supply replacements that
+use only the matched text. The helper applies each address rule once. The returned SDP rules
+belong only in a SIP-specific policy. Do not add them to the general provider defaults.
+
+Without a callback, each non-empty display name becomes `[redacted]`. The callback receives the
+name once, without source quotes and with quoted escapes decoded. It returns plain text. The
+helper escapes quotes and backslashes and writes a quoted name. An empty result removes the name.
+An identity callback, `(value) => value`, keeps the name value. A consumer can pass its injected
+hash function as `redactDisplayName`; the helper does not select `redactor.hash` automatically.
+Other SIP, credential, address, and SDP rules still apply.
+
+The callback must return a string synchronously, without control characters, within
+`redactor.limits.maxStringLength`. Invalid results throw; callback errors propagate. Malformed
+identity lists use a fixed replacement without calling the callback. There is no raw-input fallback.
+The helper limits input and complete output to four times `maxStringLength`. Oversized input
+becomes `[truncated]`. Output growth throws `RangeError`. It counts escaped callback output across
+headers before assembly and stops at the limit. Custom callbacks are trusted application code.
+
+## Memory history
+
+`createMemoryHistory({ maxRecords })` keeps the newest records in page memory.
+`maxRecords` must be a positive safe integer. It has no default. The only configuration key is
+`maxRecords`; unsupported keys reject instead of silently ignoring retention options.
+At capacity, each write removes the oldest entry before it adds the
+new record. Repeated record IDs remain separate entries. The sink keeps references to the
+redacted, frozen records from Docket core; it does not copy their payloads.
+
+`query({ areas?, from?, to? })` captures a snapshot during the call. Bounds are inclusive;
+empty areas select nothing. Results use admission order, including when timestamps move
+backwards. Each query returns a separate array. Later writes and clear do not change it.
+Changing that array does not change history or another snapshot.
+`clear()` immediately releases retained records and permits later writes. It does not change
+logger levels or the upload sink. History has no timer, flush, or stop method. Records remain
+available after the logging hub stops, until clear or page exit.
+
+History and upload accept valid immutable `LogRecord` values. They do not validate raw logger input.
+Use Docket core to create, redact, validate, and freeze records before delivery.
+
+The default client history keeps the last 1,000 records. It has no duration guarantee or separate
+area budget. At five records per second, 1,000 records cover about 200 seconds. With the default
+`maxRecordSize` of 65,536 characters, retained serialized records can total 65,536,000 characters.
+This is not a heap-byte limit. Copies, snapshots, and archives use additional memory.
+
+For separate area budgets, size limits, or age retention, inject a Hopper store:
+
+```ts
+import type { LogRecord } from '@bazariodev/docket';
+import { createMemoryStore } from '@bazariodev/hopper';
+
+const retainedHistory = createMemoryStore<LogRecord>({
+  maxAgeMs: 3_600_000,
+  maxTotalSize: 16_000_000,
+  defaultMaxSizePerArea: 1_000_000,
+  maxSizePerArea: { application: 4_000_000 },
+  maxRecordsPerArea: { application: 20_000 },
+});
+const withAreaBudgets = createDocket({
+  areas: [{ id: 'application' }],
+  redactor,
+  history: retainedHistory,
+});
+```
+
+The application supplies `redactor`. Hopper's IndexedDB history has the same area budgets and
+query filters. It already stores an `area` field and maintains an area/time index. Hopper accepts
+an omitted area for a single stream and uses `default`. Docket records retain their configured areas.
+An age limit permits expiry; it does not guarantee that size or count limits retain a full hour.
+
+### Capacity and input cost
+
+- `maxRecords` limits record count, not heap bytes. History and outbox have separate capacities
+  and can retain separate copies. Serialization limits do not give an exact heap-size limit.
+- Persistent storage also uses RAM for records, queues, and transaction work.
+- Avoid whole application stores, responses, and large dictionaries as log data. Select a few
+  fields at the call site. The field limit does not prevent enumeration of all input keys.
+- Lazy data avoids work when initial admission checks reject a call. An input that passes these
+  checks can still be expensive or fail later validation.
+- Use stable scope names. Put variable correlation IDs in context to avoid extra root loggers.
+- Release query results when no longer needed. Old snapshots retain their records after clear.
+- Stop the lifecycle owner and call helper disposers. Client stop does not erase history.
+
+## Periodic upload
+
+The application supplies `sendRecords` and `reportUploadError` in this example.
+`sendRecords(records, signal, token)` must accept the complete batch before its promise resolves.
+It owns the endpoint, account credentials, encoding, response checks, and request timeout.
+Use the token as an idempotency key in the account and application scope.
+
+```js
+import { createUploadSink } from '@bazariodev/docket/upload';
+import { createMemoryOutbox } from '@bazariodev/hopper/outbox';
+
+const outbox = createMemoryOutbox({ maxRecords: 1000 });
+const upload = createUploadSink({
+  maxBatchRecords: 100,
+  intervalMs: 15_000,
+  send: sendRecords,
+  onError: reportUploadError,
+}, outbox);
+const detachUpload = logging.addSink(upload);
+```
+
+The upload sink borrows the outbox. The application owns storage capacity, erasure, and shutdown.
+Use one upload processor per outbox. Each write returns synchronously and starts no request.
+One timer starts an automatic flush after `intervalMs`. Existing pending records also start
+this timer when the processor is created. An idle sink has no timer. Browser suspension can
+delay an attempt. The processor installs no page-exit send. An application-installed page-exit
+helper can call the hub flush and start or resume upload; select local history alone when needed.
+
+- `maxBatchRecords`, `intervalMs`, `send`, and the outbox are required. `onError` is optional.
+  A supplied observer must be a function.
+- Batch limit and interval must be positive safe integers. The interval cannot exceed
+  2,147,483,647 ms. Neither option has a default.
+- A supplied scheduler needs `setTimeout` and `clearTimeout`. The default uses host timers.
+- The outbox port needs `write`, `capture`, `flush`, `nextBatch`, `acknowledge`, and `getStatus`.
+  Docket has no runtime dependency on Hopper. Another adapter can implement this port.
+- Only one send runs at a time. `send` receives a frozen record array, an abort signal,
+  and the protected batch token. Resolve only after complete backend acceptance.
+- A failed send or acknowledgement keeps the same logical batch and token for retry.
+  Hopper reuses the array within one instance. A recovered batch can exceed a new batch limit.
+  After send resolves, the same processor retries a failed acknowledgement without another send.
+  A new processor has no such acceptance state and can send that protected token again.
+- Hopper outboxes copy JSON records, preserve FIFO order and duplicate admissions, and protect
+  one batch. Overflow removes the oldest unprotected record. If the protected batch fills
+  capacity, the incoming record is discarded. Read `droppedRecords` for these losses.
+- `getStatus()` includes the adapter mode, error, record counts, and processor `paused` and `stopped` states.
+  A failed or stopped adapter starts no automatic retry. Inspect the error and retry explicitly.
+- A rejected callback pauses automatic attempts. The consumer owns retries inside `send`.
+  An explicit `flush()` resumes the retained batch. New writes alone do not resume it.
+- A failed adapter rejects admission. The processor counts each refused record as dropped and
+  reports the storage failure once per observed failure episode. Local history keeps recording.
+  Processor drops are local to that processor; adapter overflow counts remain in adapter status.
+
+Manual `flush()` cancels the timer. It captures the admission boundary before asynchronous work.
+Writes alone do not extend it. A concurrent flush joins the same promise and extends the boundary.
+The first failure rejects that flush. A supplied `onError` observes the failure once. The reporter is not
+awaited; its throws and rejected promises are contained. A flush called synchronously by
+`onError` joins the failed operation. Do not await a flush from a callback that the flush needs.
+Adapter and processor observers report separate operations. Select one reporting path or deduplicate
+them in the application when the same failure reaches both. Repeated explicit retries can report
+new attempt failures. Keep a status observer or status checks active when using background upload.
+
+For persistent pending records, replace only the adapter:
+
+```js
+import { createIndexedDbOutbox } from '@bazariodev/hopper/outbox/indexeddb';
+
+const outbox = await createIndexedDbOutbox({
+  ...storageOptions.outbox,
+  maxRecords: 1000,
+  onError: reportUploadError,
+});
+```
+
+The asynchronous factory restores records and their protected batch before it returns.
+Supply required `databaseName` and `lockName` values in the initial options. The adapter uses
+the supplied lock name unchanged. All writers of one database must use that same lock name.
+Missing or invalid names reject before platform access.
+It requires IndexedDB and exclusive Web Locks ownership. It rejects unavailable storage,
+ownership, and incompatible schemas. It does not silently switch to memory.
+Use a separate database for download history. No database is accessed by the memory adapter.
+
+Outbox `flush()` means storage completion. Upload `flush()` also waits for backend acceptance
+and local acknowledgement. Delivery is at least once. A lost response or a new processor after
+failed acknowledgement can cause a duplicate send. Storage removal, overflow, and page exit before storage commit can
+still lose records. No adapter provides exactly-once delivery.
+
+Batch limits count records, not encoded request bytes. The client's default 100-record batch can contain
+6,553,600 serialized characters before request framing. Choose a smaller `maxBatchRecords` for
+large records. The consumer can split one protected batch into bounded requests; resolve only
+after every part is accepted. Use a stable, distinct deduplication key for each part.
+
+A permanent rejection must not silently become acceptance. In particular, do not treat every
+4xx response as success. The consumer can stop the processor, inspect the protected batch, report
+an intentional discard, then acknowledge that exact token. `outbox.clear()` discards all pending
+records. Both are application data-loss decisions. Authentication failures must not switch a batch
+to another account's credentials.
+
+## Export and download
+
+```js
+import { createLogBundle } from '@bazariodev/docket/export';
+import { downloadBlob } from '@bazariodev/docket/browser';
+import * as archive from '@bazariodev/baler';
+
+const bundle = await createLogBundle({
+  source: history,
+  redactor,
+  files: [{ name: 'application.log', areas: ['application', 'network'] }],
+}, archive);
+downloadBlob(bundle.blob, bundle.fileName);
+```
+
+The bundle uses one fixed snapshot while recording continues. Download neither drains history
+nor acknowledges upload records. It works without an uploader and during upload failure.
+The manifest uses the minimum and maximum selected timestamps for its actual range. Returned
+snapshots and files belong to their caller. Clear cannot erase those returned values.
+
+`maxInputSize` defaults to 32,000,000 UTF-8 bytes across all files and the manifest.
+The exporter checks each formatted record, including its trailing newline, before retaining it.
+It checks custom output on return and checks the serialized manifest before archive assembly.
+Overflow rejects with `RangeError` and stops later rendering and archive work. The archive
+provider also checks the final input size.
+
+This limit bounds retained export text, not peak heap use. The source can allocate its snapshot
+before formatting. One current record, a custom renderer, or manifest serialization can allocate
+before its size check. Synchronous custom rendering cannot be interrupted.
+
+### JSON and NDJSON
+
+Use queried records directly for structured output. They have already passed redaction:
+
+```js
+const records = await history.query();
+const json = JSON.stringify(records);
+const ndjson = records.map((record) => `${JSON.stringify(record)}\n`).join('');
+```
+
+These application-owned strings have no bundle byte limit. Bound the selected history and
+release snapshots and strings when no longer needed. Do not add raw input after redaction.
+
+## Shutdown and account changes
+
+`createDocket().flush()` waits for its sinks, including delivery through a configured uploader.
+Its `stop()` cancels upload before sink cleanup and starts no final send. Flush explicitly
+before stop when application policy requires delivery. Rejection pauses automatic upload;
+another explicit flush resumes it. The consumer owns request retry and timeout policy.
+
+Browser helpers have separate disposers. This example reuses the memory client from Usage:
+
+```js
+import { captureGlobalErrors } from '@bazariodev/docket/browser';
+
+const disposeErrors = captureGlobalErrors(
+  docket.getLogger('application', 'Global'),
+);
+try {
+  await docket.flush();
+} finally {
+  disposeErrors();
+  await docket.stop();
+}
+```
+
+Stop preserves history. Use the [account cleanup sequence below](#account-cleanup)
+when application policy requires erasure.
+
+`logging.stop()` closes admission, flushes each sink, then stops each sink. The uploader's flush
+includes retained work when it joins an active operation. A failure still runs sink cleanup and
+reaches the hub's aggregate error. History remains available for download.
+
+### Account cleanup
+
+For logout, stop sending before the hub can flush the uploader. Then erase and close storage:
+
+```js
+const failures = [];
+for (const step of [
+  () => logging.resetLevel(),
+  () => upload.stop(),
+  () => outbox.clear(),
+  () => logging.stop(),
+  () => outbox.stop(),
+  () => history.clear(),
+]) {
+  try {
+    await step();
+  } catch (error) {
+    failures.push(error);
+  }
+}
+if (failures.length) throw new AggregateError(failures, 'Cleanup failed');
+```
+
+For shutdown that preserves pending records, stop the uploader, then stop the outbox.
+Upload stop cancels its timer, signals the active send, and starts no final send or retry.
+It resolves without waiting for an uncooperative send. An interrupted flush rejects with
+`AbortError`. Late send settlement cannot start an acknowledgement or restart processing.
+An acknowledgement started before stop can still complete. Store clear and stop wait for
+storage work. Upload stop neither clears nor closes the borrowed adapter.
+Writes after processor stop are ignored. Processor flush after stop resolves without sending.
+
+`detachUpload()` prevents future hub delivery. The application must still stop the uploader.
+The application owns account changes, credentials, logger-level resets, and cancellation of
+outstanding downloads. Bind each uploader to its original account; stop it before credentials
+change, then create a new uploader. Local clear does not stop or flush upload.
+
+`createLogHistory` and its account/session types are removed. The replacement has no account
+controller or automatic legacy cleanup. The memory helper never accesses disk history.
+Deployed consumers need a separate migration for legacy storage, including prior memory mode.
+Switching to memory does not erase that storage. Standalone `/indexeddb` remains available.
+
+TypeScript imports from the former `/history` entry also change:
+
+| Former type | Current entry |
+| --- | --- |
+| `CopyRecordsOptions` | `@bazariodev/hopper` |
+| `LogOverflowStrategy`, `LogStoreError`, `MemoryLogStoreOptions` | `@bazariodev/docket/indexeddb` |
+
+Use the new `/history` types only for FIFO memory history. Hopper exposes its generic store
+types directly; Docket's `/indexeddb` keeps its logging-specific compatibility types.
+
+### Migrate storage from 0.0.0
+
+The old managed history could create an empty database and owner metadata during account
+transitions, even in memory mode. Use the original database override if one was supplied.
+Otherwise its names were:
+
+| Resource | Legacy name |
+| --- | --- |
+| Managed database | `bazario-logging:history:${leaseKey}` |
+| Managed localStorage metadata | `bazario-logging:metadata:${databaseName}` |
+| Managed or standalone database lock | `JSON.stringify(['bazario:logging:indexeddb', databaseName])` |
+| Standalone database without an override | `bazario-logging` |
+
+The metadata can contain a salt, full owner digest, level overrides, and a persistent-mode key.
+Remove it as well as the database when that legacy history is no longer needed. Stop old clients
+first. A new Hopper default lock does not exclude a live 0.0.0 writer; supply the exact legacy lock.
+Keep this lock protocol until all writers of that database have migrated. Use separate names
+for a new account schema.
+
+The application owns permanent erasure of its dedicated database. Acquire its exact exclusive
+lock with `ifAvailable: true`; refuse when it is held. Under that lock, call
+`indexedDB.deleteDatabase(databaseName)` and await native success or error. After success, call
+`localStorage.removeItem(metadataKey)` for the managed history key. Do not remove unrelated
+origin data. Deletion creates no database and needs no compatible schema or metadata writes.
+The same path can erase a corrupt dedicated outbox when schema-preserving clear cannot proceed.
+
+Native deletion cannot be canceled. If another connection blocks it, close old tabs or connections
+and keep the lock until deletion settles. A timeout must not release ownership while deletion
+remains pending. Never report completed erasure before native success. See
+[MDN deleteDatabase](https://developer.mozilla.org/en-US/docs/Web/API/IDBFactory/deleteDatabase).
+The repository's consumer example supplies `eraseDiagnosticStorage` for this operation;
+it is application wiring, not a Docket export.
+
+## Persistent storage
+
+Use a Hopper store directly as a sink and an export source. Both Hopper history adapters
+sort by timestamp, run ID, and sequence. They keep the first retained `(runId, seq)` record.
+This differs from the FIFO helper, which preserves duplicate admissions.
+
+```js
+import { createIndexedDbStore } from '@bazariodev/hopper/indexeddb';
+
+const history = createIndexedDbStore({
+  ...storageOptions.history,
+});
+const detachHistory = logging.addSink(history);
+// Pass history as the source for createLogBundle.
+await history.flush();
+const status = history.getStatus();
+```
+
+`/indexeddb` is an optional structural adapter. Supply Hopper's factory as its second argument.
+Both `databaseName` and `lockName` are required. The adapter forwards them unchanged and rejects
+missing or invalid names before calling the provider. It supplies no database or lock default.
+
+The supplied Hopper store first tries an exclusive database lock. A blocked or unavailable lock selects memory
+fallback for that instance's lifetime. It cannot later replay that fallback into another owner's
+history. A new instance can try ownership again. With `allowUnprotected: true`, failed acquisition
+permits IndexedDB access without a lease. The store still tries the lock first.
+
+Unprotected access cannot prevent another writer from recording after clear. It cannot establish
+stable account history. Read `unprotected` and `unavailableHistory` from status after an operation.
+Status reads are synchronous; initial acquisition is asynchronous.
+
+An open or write failure with permitted access starts bounded memory fallback. Recovery retries
+every ten minutes. A failed write batch is lost and its flush rejects. Other pending records move
+to fallback. Successful recovery removes copied fallback records only after commit.
+
+`clearIndexedDbLogStore(options, clearStore)` supplies the same logging database and lock names
+to a standalone cleanup provider. With Hopper `clearIndexedDbStore`, it clears existing records
+and metadata without creating a database. Listing can still access IndexedDB. The new memory
+entries never call this cleanup path.
+
+## Behavior
+
+`isActive` is an optional admission guard. Returning `false` stops a record before conversion or
+delivery. The hub checks it again after application callbacks. `createDocket` captures this
+function from the original options, including prototype methods, and calls it with that options object as
+its receiver. State changes on the original object take effect on later checks. A replacement
+method does not replace the captured gate. If the gate stops the client, the current record is
+blocked before delivery. The application supplies this guard when it needs one.
+
+- Levels are `debug`, `info`, `warn`, and `error`. Default area level is `info`.
+- Data functions run only after admission. No sinks, stop, levels, and storm limits can prevent admission.
+- The first 1,000 root loggers are cached by area and scope. Further pairs are uncached; one
+  `scope` diagnostic reports the limit. Put correlation IDs in child context.
+- Each record is redacted once, then validated, copied, and deeply frozen before sink delivery.
+- Custom redactors must return JSON with dense arrays. Invalid output is dropped and reports `redactor`.
+- Conversion does not call getters or `toJSON`. It bounds strings, structure, and serialized size.
+- Error causes and aggregate errors become structured data. Non-finite numbers become null.
+- Console and default file text include custom Error fields as compact JSON. Their keys and
+  values use the same control-character escaping as other Error details.
+- Record validation checks fixed record and Error fields separately from application data. The full
+  serialized record must fit `maxRecordSize`. Fixed level values remain intact at small text limits.
+- Default storm allowance is 100 records per area/scope each second. One timer reports suppression.
+- Sink failures do not stop other sinks. Recursive logging from sinks and reporters is rejected.
+
+The standalone store defaults and recovery rules below describe the Hopper provider.
+They do not apply to the FIFO history helper or outbox adapters.
+Other providers must state their supported behavior.
+
+- Queries use inclusive time bounds and order by time, run ID, then sequence. Empty areas select nothing.
+- Both stores keep the first retained `(runId, seq)` record. Eviction releases its identity.
+- Default budgets are 1,000,000 JSON characters per area, 16,000,000 total, and 24-hour age.
+- IndexedDB also defaults to 20,000 records per area, 250 records per batch, and a one-second flush interval.
+- IndexedDB recovery uses oldest-record eviction for copied and queued fallback records. This replay does not call `onRotate`.
+- Pending plus active database records are limited to 1,000 records and 4,000,000 JSON characters.
+- Expired data is excluded from queries. Disk expiry cleanup runs at open and write, without a timer.
+- `flush()` means local transaction commit. Page exit is best effort; crash survival is not guaranteed.
+- Detach removes sink delivery. The sink's lifecycle owner must stop it separately.
+- A stopped store ignores writes. Its query and clear remain available under their access rules.
+
+## API
+
+| Entry | Exports |
+| --- | --- |
+| Root | `createLogging`, `createConsoleSink`, `formatRecord` |
+| `/client` | `createDocket(options)` |
+| `/redaction` | `createRedactor(policy, providers)` |
+| `/indexeddb` | `createIndexedDbLogStore(options, createStore)`, `clearIndexedDbLogStore(options, clearStore)` |
+| `/history` | `createMemoryHistory(options)` |
+| `/upload` | `createUploadSink(options, outbox)` |
+| `/export` | `createLogBundle(options, archive)` |
+| `/browser` | `captureGlobalErrors`, `flushOnPageHide`, `collectBrowserEnvironment`, `downloadBlob` |
+| `/sip` | `createSipTools(textRules)`, `describeSipMessage`. The tools expose `redactSipMessage`, `describeSipMessage`, and `SDP_TEXT_RULES`. |
+| `/devtools` | `installConsoleApi` |
+
+| Component | Options and methods |
+| --- | --- |
+| Docket client | Hub options plus `history` and `upload`. Returns hub methods, `history`, `outbox`, and `upload`. Disabled features are `undefined`. Stop cancels sending before storage shutdown. |
+| Hub | Required `areas`, `redactor`; optional `sinks`, `context`, `levelStorage`, `maxOverrideMs`, `stormLimit`, `scheduler`, clocks, `createRunId`, `onError`, `isActive`. Methods: `getLogger`, `setContext`, `setLevel`, `resetLevel`, `reloadLevels`, `getLevels`, `addSink`, `flush`, `stop`. |
+| Logger | `debug`, `info`, `warn`, `error` accept `(message, data?)`. `child({ scope?, context? })` adds bindings. |
+| Redactor | Policy: `version`, `hash`, `fields`, `unknownFields`, `text`, `limits`. Methods: `redact`, `redactValue`, `redactText`, `mask`, optional `hash`. Resolved `limits` and `version` are public. |
+| Memory store | `maxSizePerArea`, `defaultMaxSizePerArea`, `maxTotalSize`, `maxAgeMs`, `now`, `overflowStrategy`, `onRotate`, `scheduler`, `onError`. Methods: `write`, `query`, `flush`, `clear`, `stop`, `getStatus`. |
+| IndexedDB store | Memory options plus required `databaseName` and `lockName`, optional `indexedDB`, `locks`, `allowUnprotected`, batch/queue/interval/count limits, and `fallback`. |
+| Memory history | Required `maxRecords`. Queue creation is internal. Methods: `write`, `query`, `clear`. |
+| Upload sink | Required `maxBatchRecords`, `intervalMs`, `send`, and an outbox. Optional `onError` and `scheduler`. Methods: `write`, `flush`, `stop`, `getStatus`. |
+| Bundle | Required `source`, `redactor`, `files`, and the separate archive capability. Optional time bounds, `manifest`, `fileName`, `maxInputSize`, clock, scheduler. Returns `blob`, `fileName`, file counts. |
+| Supplied Hopper copy helper | `copyRecords(from, to, { maxChunkRecords?, maxChunkSize? })`; defaults are 100 records and 1,000,000 JSON characters. It flushes between chunks. |
+| Console sink | Optional minimum `level` and injected `console`. |
+| Custom sink | Implement `LogSink.write(record)`. Optional `flush` and `stop` return promises. |
+| Console API | Inject level controls and optional `clear` and `exportBundle`. Optional `name`, `target`. Returns cleanup. |
+
+Redaction defaults: depth 6; strings 16,384 characters; arrays 100 entries; objects 100 keys;
+1,000 nodes; 65,536 JSON characters per record. Field rules are case-insensitive at every depth:
+`keep`, `drop`, `mask`, `hash`. Unknown fields default to keep. Hash rules require an injected hash.
+An explicit `text: []` disables default text rules. Global non-sticky regular expressions are required.
+Custom patterns and callbacks are trusted application code.
+
+SIP redaction preserves protocol structure and replaces identity and credential values. Unknown
+SIP bodies become content-type and byte-count markers. The application owns any selected hasher
+and its dependency. The package does not implement a cryptographic algorithm.
+
+Bundle filenames cannot contain paths, reserved device names, or manifest variants. Comparison
+uses NFC and ignores case. Empty files are omitted; the manifest retains their zero counts.
+File names, each file's area list, and the download name are checked before the source query. Its default timestamp is
+the call's start time. The manifest build time is recorded after rendering.
+Custom renderers are synchronous. Built-in formatting yields during large files. The
+[export byte limit](#export-and-download) applies during formatting and before compression.
+The supplied Baler implementation uses raw deflate when available and stored entries otherwise.
+The manifest contains ranges, counts, truncation, warnings, policy versions, store status, and
+redacted application metadata. It contains no history key.
+
+`formatRecord` produces human-readable text with flat labels. Context and field keys can repeat
+header names such as `runId` or `message`. Choose distinct data names and use structured records
+for machine parsing; the text format does not guarantee unique keys across those sections.
+
+Browser listeners are explicit and return cleanup. Environment defaults are language, UTC offset,
+display mode, and online state. Extra fields need explicit selection. Optional reads use a 500 ms
+deadline by default. Unknown field names reject before platform reads. Collection never requests capture or permission and omits device IDs and labels.
+
+External service integrations follow the [synchronous sink contract](#console-output-and-custom-sinks).
+The application owns service mapping, network delivery, and SDK lifecycle.
+
+## Privacy
+
+Records contain time, run ID, sequence, area, scope, level, message, and selected context, data,
+and Error fields after the configured redactor runs. Application policy determines which private
+values remain. A run ID is a pseudonym, not an account permission or a guarantee of anonymity.
+Do not use direct account identifiers in database names. The application supplies an opaque scope.
+
+Default history stays in page memory until eviction, clear, or page exit. A memory outbox also loses
+records on reload. IndexedDB history and outboxes are device storage and can survive restart.
+History follows its budgets. Outbox records remain until acknowledgement, clear, or capacity loss;
+outboxes have no age expiry. Stop preserves persistent records. Clear cannot erase exported files,
+returned snapshots, records already sent, or copies held by application code.
+
+Upload is disabled unless configured. The consumer selects the endpoint and every third party,
+owns credentials, retry, backend retention, access, and deletion. The application must apply its
+permission policy separately to local recording and background upload. Enabling one does not
+grant permission for the other. Docket adds no consent UI or external service.
+
+Delivery is at least once. The backend can receive duplicates and must deduplicate batch tokens
+within the original account scope. Keep account databases and sender credentials separate after
+forced sign-out, failed cleanup, and restart. An old account's records must never use a new
+account's sender. Retry failed cleanup under the old account's known resource names.
+
+## Errors
+
+Logger writes never throw. Configuration errors and missing capabilities can throw `TypeError`. The hub reports sources
+`data`, `redactor`, `sink`, `storage`, `scope`, and `reentry` through `onError`. Flush and stop attempt
+all sinks and reject with an aggregate error on failure. Hub-generated diagnostics use codes
+`recursive-logging`, `root-logger-cache-limit`, and `stopped`. Callback failures keep their original errors.
+
+Standalone store errors have codes `open`, `write`, `read`, `quota`, `overflow`, `ownership`,
+`clear`, `upgrade`, and `rotation`. Memory history rejects invalid query filters with `TypeError`.
+Invalid memory-history options throw `TypeError`. The upload factory validates its options and
+outbox before it schedules or sends work.
+
+Upload flush rejects on the first storage, send, or acknowledgement failure.
+A supplied `onError` receives each failed attempt once,
+including an adapter `AbortError` while the sink is active. Sink stop instead rejects interrupted
+flushes with `AbortError` without reporting an upload failure. Export and developer actions reject
+to their caller. These failures do not remove retained local history.
+
+## TypeScript
+
+Declarations are provided for ESM and CommonJS. Core, memory history, redaction, SIP, and devtools
+need only ES2022 types. Upload and client need `AbortSignal` declarations from the target runtime.
+Browser, persistence, and export entries use DOM types. No entry declaration imports a provider
+package. The logger satisfies the existing workspace logger ports without an adapter.
+Area inference rejects unknown area names.
+Import `DocketOptions`, `Docket`, `HistoryClient`, `OutboxClient`, and `DocketUploadOptions` from
+`@bazariodev/docket/client`. Hopper clients satisfy these local structural types.
+Import `MemoryHistoryOptions` and `MemoryHistory` from `@bazariodev/docket/history`. Import
+`UploadSinkOptions`, `UploadSinkStatus`, `UploadSink`, and `UploadOutbox` from
+`@bazariodev/docket/upload`. Hopper's `Outbox<LogRecord>` satisfies the upload port.
+Queue types are internal. Consumers do not supply or import them for memory history.
+Import `LogRecord` from `@bazariodev/docket`. Use `createMemoryStore<LogRecord>` when selecting
+Hopper's standalone store or rotation snapshots. The export source receives a query argument.
+
+## License
+
+[MIT](./LICENSE)