@nomix-ai/nomix-harness 0.2.6 → 0.2.7

package/node_modules/@nomix-ai/nomix-attachment-local/lib/types/image.d.ts

@@ -0,0 +1,54 @@
+/** Raster inspection: full decode at admission, header-only probe on verified reads. */
+import type { ImageMediaType } from '@nomix-ai/nomix-attachment';
+/** Decoded metadata from a supported image. */
+export interface DetectedImage {
+    mediaType: ImageMediaType;
+    /** Intrinsic width with EXIF orientation applied — the width a viewer perceives. */
+    width: number;
+    /** Intrinsic height with EXIF orientation applied — the height a viewer perceives. */
+    height: number;
+    /** Whether the container carries more than one frame. */
+    animated: boolean;
+    /** Whether the bytes carry descriptive metadata, a color profile, or orientation. */
+    carriesMetadata: boolean;
+    /** Sharp sample depth reported for the decoded channels. */
+    depth: string;
+    /** Sharp colour space reported for the decoded pixels. */
+    space: string;
+    /** Whether decoded pixels carry an alpha channel. */
+    hasAlpha: boolean;
+}
+/**
+ * Check alpha metadata for bytes produced by this package's encoders.
+ * Sharp/libvips may omit an all-opaque alpha plane from WebP output; every
+ * other addition or removal indicates that the encoded result is incompatible
+ * with its source facts.
+ * @param sourceHasAlpha - whether the source bytes declare an alpha plane, or undefined when the source frame is unspecified.
+ * @param output - decoded media type and alpha metadata from the encoded result.
+ * @returns whether the output alpha metadata is compatible with the source.
+ */
+export declare function encodedAlphaIsCompatible(sourceHasAlpha: boolean | undefined, output: Pick<DetectedImage, 'mediaType' | 'hasAlpha'>): boolean;
+/**
+ * Parse a supported raster's header and return its intrinsic metadata without
+ * decoding pixels. Digest-verified reads use this: admission already proved
+ * that these exact bytes decode completely, so the read path only re-derives
+ * the reference fields instead of paying the full-raster decode again.
+ * @param data - complete encoded image bytes.
+ * @returns verified format and dimensions.
+ */
+export declare function probeImage(data: Uint8Array): Promise<DetectedImage>;
+/** Admission limits applied to a decoded raster's intrinsic dimensions. */
+export interface DecodedImageLimits {
+    /** Decoded-pixel (width times height) admission limit. */
+    maxPixels?: number;
+    /** Per-side admission limit applied to width and height independently. */
+    maxDimension?: number;
+}
+/**
+ * Fully decode a supported raster and return its intrinsic metadata.
+ * @param data - complete encoded image bytes.
+ * @param limits - intrinsic-dimension admission limits.
+ * @returns verified format and dimensions.
+ */
+export declare function detectImage(data: Uint8Array, limits?: DecodedImageLimits): Promise<DetectedImage>;
+//# sourceMappingURL=image.d.ts.map

package/node_modules/@nomix-ai/nomix-attachment-local/lib/types/index.d.ts

@@ -0,0 +1,76 @@
+/** Local durable attachment backend rooted below `NOMIX_HOME`. @module @nomix-ai/nomix-attachment-local */
+import { Context } from '@nomix-ai/cordis';
+import z from '@nomix-ai/schemastery';
+import { AttachmentStore } from '@nomix-ai/nomix-attachment';
+import type { ImageAttachmentLimits, ImageAttachmentRef, ImageRequestPolicy, RequestImageAttachment, SaveImageAttachment, StoredImageAttachment } from '@nomix-ai/nomix-attachment';
+import type { NormalizationPolicy } from './normalization.ts';
+export { canPassThroughNormalization, normalizeImage } from './normalization.ts';
+export type { NormalizedImage, NormalizationPolicy } from './normalization.ts';
+export { commitPreparedImageFile, prepareImageFile, readImageFile, saveImageFile, validateImageFile } from './store.ts';
+export type { PreparedImageFile } from './store.ts';
+export { readRequestImageFile, requestImageDimensions, requestImageVariantId } from './request-image.ts';
+/** Default maximum encoded bytes for one submitted image; oversized sources are refused, not shrunk. */
+export declare const DEFAULT_MAX_IMAGE_BYTES: number;
+/** Default maximum images in one prompt. */
+export declare const DEFAULT_MAX_IMAGES_PER_MESSAGE = 20;
+/** Default maximum aggregate image bytes in one prompt. */
+export declare const DEFAULT_MAX_MESSAGE_IMAGE_BYTES: number;
+/** Default maximum intrinsic pixels for one submitted image. */
+export declare const DEFAULT_MAX_IMAGE_PIXELS = 64000000;
+/** Default per-side pixel cap for one submitted image. */
+export declare const DEFAULT_MAX_IMAGE_DIMENSION = 8192;
+/**
+ * Default long-edge target of the stored normalized image. A larger source
+ * is admitted and downscaled to this edge, so admission bounds what rides
+ * every later model request without refusing ordinary large sources.
+ */
+export declare const DEFAULT_NORMALIZED_IMAGE_MAX_DIMENSION = 2048;
+/** Default independent safety cap for one stored normalized image. */
+export declare const DEFAULT_NORMALIZED_IMAGE_MAX_BYTES: number;
+/** Conservative default number of simultaneous native image transformations per store. */
+export declare const DEFAULT_IMAGE_COMPRESSION_CONCURRENCY = 2;
+/** Maximum configurable native image transformations per store. */
+export declare const MAX_IMAGE_COMPRESSION_CONCURRENCY = 8;
+/** Local attachment backend configuration. */
+export interface Config {
+    /** Explicit harness home; omitted follows `NOMIX_HOME`, then `~/.nomix`. */
+    nomixHome?: string;
+    /** Maximum encoded bytes accepted for one submitted image. Default: 20 MiB. */
+    maxImageBytes?: number;
+    /** Maximum image count accepted in one submitted message. Default: 20. */
+    maxImagesPerMessage?: number;
+    /** Maximum aggregate encoded image bytes accepted in one submitted message. Default: 200 MiB. */
+    maxMessageImageBytes?: number;
+    /** Maximum intrinsic width multiplied by height accepted for one submitted image. Default: 64,000,000. */
+    maxImagePixels?: number;
+    /** Maximum intrinsic width and maximum intrinsic height accepted for one submitted image. Default: 8192px. */
+    maxImageDimension?: number;
+    /** Long-edge pixel cap of the stored provider-independent normalized image. */
+    normalizedImageMaxDimension?: number;
+    /** Encoded-byte safety cap of the stored provider-independent normalized image. */
+    normalizedImageMaxBytes?: number;
+    /** Maximum simultaneous normalization or request-image transformations in this service instance. */
+    imageCompressionConcurrency?: number;
+}
+/** Persistent content-addressed local attachment store. */
+export declare class LocalAttachmentStore extends AttachmentStore {
+    static Config: z<Config>;
+    /** Absolute versioned storage root. */
+    readonly root: string;
+    readonly imageLimits: ImageAttachmentLimits;
+    /** Resolved provider-independent normalization policy. */
+    readonly normalizationPolicy: Readonly<NormalizationPolicy>;
+    /** Resolved instance-level compression limit. */
+    readonly imageCompressionConcurrency: number;
+    private readonly compression;
+    private readonly requestInflight;
+    constructor(ctx: Context, config: Config);
+    validateImage(input: SaveImageAttachment): Promise<void>;
+    saveImages(inputs: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>;
+    saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef>;
+    readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>;
+    readImageRequest(ref: ImageAttachmentRef, policy: ImageRequestPolicy, signal?: AbortSignal): Promise<RequestImageAttachment>;
+    private requestVersion;
+}
+export default LocalAttachmentStore;
+//# sourceMappingURL=index.d.ts.map

package/node_modules/@nomix-ai/nomix-attachment-local/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned invariant companion for `@nomix-ai/nomix-attachment-local`. @module @nomix-ai/nomix-attachment-local/invariant */
+import type { Context } from '@nomix-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "attachment-local-invariant";
+/** Services required before package ownership can be reserved. */
+export declare const inject: string[];
+/**
+ * Register the package invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the registration disposer.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/node_modules/@nomix-ai/nomix-attachment-local/lib/types/normalization.d.ts

@@ -0,0 +1,44 @@
+/** Deterministic provider-independent image normalization. */
+import { type Sharp } from 'sharp';
+import type { ImageMediaType } from '@nomix-ai/nomix-attachment';
+import type { DetectedImage } from './image.ts';
+/** Deployment-resolved policy for the persisted normalized attachment. */
+export interface NormalizationPolicy {
+    /** Long-edge cap in pixels; larger sources are downscaled proportionally. */
+    maxDimension: number;
+    /** Independent safety cap for encoded normalized image bytes. */
+    maxBytes: number;
+}
+/** Normalized bytes beside the facts recorded by a durable reference. */
+export interface NormalizedImage {
+    data: Uint8Array;
+    mediaType: ImageMediaType;
+    width: number;
+    height: number;
+}
+/**
+ * Whether bytes already satisfy the normalization requirements.
+ * @param detected - fully decoded source facts.
+ * @param bytes - encoded source length.
+ * @param policy - resolved normalization limits.
+ * @returns whether the source can pass through byte-identically.
+ */
+export declare function canPassThroughNormalization(detected: DetectedImage, bytes: number, policy: NormalizationPolicy): boolean;
+/**
+ * Classify a bounded pixel sample without assuming that a PNG source is a screenshot.
+ * @param pipeline - oriented sRGB source pipeline before output resizing.
+ * @returns whether the nearest-neighbour sample stays within the low-color threshold.
+ */
+export declare function hasLowColourCount(pipeline: Sharp): Promise<boolean>;
+/**
+ * Produce the persisted provider-independent normalized version of one fully decoded source.
+ * The source is passed through only when it is already clean, single-frame, 8-bit sRGB/sRGBA,
+ * and inside both normalization limits. Re-encoding never removes transparency. After the fixed
+ * quality floor is reached, dimensions continue shrinking until the independent byte cap holds.
+ * @param data - complete admitted source bytes.
+ * @param detected - fully decoded source facts.
+ * @param policy - resolved independent normalization limits.
+ * @returns verified provider-independent normalized bytes and metadata.
+ */
+export declare function normalizeImage(data: Uint8Array, detected: DetectedImage, policy: NormalizationPolicy): Promise<NormalizedImage>;
+//# sourceMappingURL=normalization.d.ts.map

package/node_modules/@nomix-ai/nomix-attachment-local/lib/types/request-image.d.ts

@@ -0,0 +1,35 @@
+/** Deterministic cached image versions for model requests. */
+import { ImageVariantId } from '@nomix-ai/nomix-attachment';
+import type { ImageAttachmentRef, ImageRequestPolicy, RequestImageAttachment, StoredImageAttachment } from '@nomix-ai/nomix-attachment';
+/** Transform version included in every cache and upload-index identity. */
+export declare const REQUEST_IMAGE_TRANSFORM_VERSION = "request-image-v4";
+/** DeepSeek request versions normally fit at these two preferred qualities. */
+export declare const REQUEST_IMAGE_QUALITIES: readonly [85, 80];
+/**
+ * Compute aspect-preserving integer dimensions within a hard total-pixel budget.
+ * @param width - positive source width.
+ * @param height - positive source height.
+ * @param maxPixels - positive width-times-height cap.
+ * @returns inward-rounded dimensions; small images are not enlarged.
+ */
+export declare function requestImageDimensions(width: number, height: number, maxPixels: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Complete deterministic identity for one attachment and route-owned request policy.
+ * @param attachment - provider-independent durable normalized attachment reference.
+ * @param policy - route-owned pixel and byte policy.
+ * @returns branded digest over every request transform input.
+ */
+export declare function requestImageVariantId(attachment: ImageAttachmentRef, policy: ImageRequestPolicy): ReturnType<typeof ImageVariantId>;
+/**
+ * Generate or reuse one request image below the local attachment root.
+ * @param root - absolute versioned attachment storage root.
+ * @param attachment - verified normalized attachment bytes and reference.
+ * @param policy - exact route request-image policy.
+ * @param signal - optional cancellation for cache I/O and image transformation.
+ * @returns verified request bytes and deterministic variant identity.
+ */
+export declare function readRequestImageFile(root: string, attachment: StoredImageAttachment, policy: ImageRequestPolicy, signal?: AbortSignal): Promise<RequestImageAttachment>;
+//# sourceMappingURL=request-image.d.ts.map

package/node_modules/@nomix-ai/nomix-attachment-local/lib/types/store.d.ts

@@ -0,0 +1,54 @@
+/** Content-addressed, owner-private local attachment storage. */
+import type { ImageAttachmentLimits, ImageAttachmentRef, SaveImageAttachment, StoredImageAttachment } from '@nomix-ai/nomix-attachment';
+import type { NormalizationPolicy } from './normalization.ts';
+/**
+ * Run the full admission policy for one image without touching storage,
+ * including normalization: a batch whose members all validate cannot later
+ * be refused by the normalized image byte cap during publication.
+ * @param input - encoded bytes and declared metadata.
+ * @param limits - resolved source admission policy.
+ * @param policy - resolved normalization policy.
+ * @returns completion after the raster has been decoded and its normalized version proven to fit.
+ */
+export declare function validateImageFile(input: SaveImageAttachment, limits: ImageAttachmentLimits, policy: NormalizationPolicy): Promise<void>;
+/** Fully prepared normalized object, verified before any batch member is persisted. */
+export interface PreparedImageFile {
+    /** Deterministic normalized bytes whose digest is {@link ref.attachmentId}. */
+    data: Uint8Array;
+    /** Durable reference describing {@link data}. */
+    ref: ImageAttachmentRef;
+}
+/**
+ * Decode, normalize, and verify one submitted image without touching storage.
+ * @param input - submitted encoded bytes and declared media type.
+ * @param limits - source admission policy.
+ * @param policy - independent normalization policy.
+ * @returns immutable reference facts beside bytes ready for atomic publication.
+ */
+export declare function prepareImageFile(input: SaveImageAttachment, limits: ImageAttachmentLimits, policy: NormalizationPolicy): Promise<PreparedImageFile>;
+/**
+ * Publish one already verified normalized image below a versioned attachment root.
+ * @param root - absolute `NOMIX_HOME/attachments/v1` root.
+ * @param prepared - deterministic normalized bytes and reference.
+ * @returns durable content-addressed normalized image reference.
+ */
+export declare function commitPreparedImageFile(root: string, prepared: PreparedImageFile): Promise<ImageAttachmentRef>;
+/**
+ * Decode and normalize one image once, then publish the prepared object.
+ * @param root - absolute `NOMIX_HOME/attachments/v1` root.
+ * @param input - submitted encoded bytes and declared media type.
+ * @param limits - resolved source admission policy.
+ * @param policy - resolved normalization policy.
+ * @returns durable content-addressed normalized image reference.
+ */
+export declare function saveImageFile(root: string, input: SaveImageAttachment, limits: ImageAttachmentLimits, policy: NormalizationPolicy): Promise<ImageAttachmentRef>;
+/**
+ * Read and verify one content-addressed image.
+ * @param root - absolute `NOMIX_HOME/attachments/v1` root.
+ * @param ref - reference recorded in the session log.
+ * @param signal - optional cancellation for filesystem and verification work.
+ * @returns verified bytes and reference.
+ * @throws the signal reason when aborted, or an AttachmentError when verification fails.
+ */
+export declare function readImageFile(root: string, ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>;
+//# sourceMappingURL=store.d.ts.map

package/node_modules/@nomix-ai/nomix-attachment-local/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@nomix-ai/nomix-attachment-local",
+  "description": "Private content-addressed NOMIX_HOME attachment storage",
+  "version": "0.2.7",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ditgaldev/nomix-harness.git",
+    "directory": "packages/attachment/attachment-local"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@nomix-ai/nomix-attachment": "0.2.7",
+    "@nomix-ai/nomix-invariants": "0.2.7",
+    "@nomix-ai/nomix-home-paths": "0.2.7",
+    "@nomix-ai/cordis": "4.0.1"
+  },
+  "dependencies": {
+    "@nomix-ai/schemastery": "3.18.1",
+    "sharp": "^0.35.3"
+  },
+  "devDependencies": {
+    "@nomix-ai/nomix-attachment": "workspace:^",
+    "@nomix-ai/nomix-invariants": "workspace:^",
+    "@nomix-ai/nomix-home-paths": "workspace:^",
+    "@nomix-ai/cordis": "workspace:^"
+  }
+}

package/node_modules/@nomix-ai/nomix-authorization/lib/index.js

@@ -0,0 +1,248 @@
+import { Service } from "@nomix-ai/cordis";
+import { HarnessError } from "@nomix-ai/nomix-llm";
+//#region lib/types/index.js
+/**
+* Service Definition for the authorization capability seam (`ctx.authorization`):
+* obtaining a credential nobody can supply from configuration alone, because
+* getting it requires a conversation with the human — open this page, paste
+* that code, pick an account.
+*
+* The seam owns the conversation and the lifecycle; it never owns the protocol.
+* A plugin that knows how to obtain its own credential registers a flow keyed
+* by the `CredentialKey` that flow writes, and the flow talks to whatever
+* surface started it through one neutral vocabulary of notices and prompts. So
+* a second authorization protocol arrives as another flow rather than as
+* another seam, and a surface that renders one flow renders all of them.
+*
+* ```ts
+* const dispose = ctx.authorization.registerFlow({
+*   key: credentialKey('llm-pi-ai', 'openai-codex'),
+*   label: 'ChatGPT (Codex)',
+*   methods: [{ id: 'oauth', label: 'Sign in with ChatGPT' }],
+*   async run(session) {
+*     session.notify({ message: 'Continue in your browser', url })
+*     await commitThroughCredentials(await exchange(session.signal))
+*   },
+* })
+* ```
+*
+* @module @nomix-ai/nomix-authorization
+*/
+/** Stable error taxonomy for authorization failures. */
+var AuthorizationError = class extends HarnessError {
+	constructor(message, code, options) {
+		super(message, code, options);
+		this.name = "AuthorizationError";
+	}
+};
+/**
+* The rejection an {@link AuthorizationInteraction.prompt} uses to say the
+* human declined — dismissed the question, chose not to answer — rather than
+* that the surface broke. An attempt whose flow fails after a prompt was
+* declined settles as `cancelled`, the same outcome as a withdrawn signal,
+* because the human saying no is a refusal, not a breakage. Only a human's
+* "no" may reject with this class: a prompt withdrawn by its own `signal` (a
+* flow retiring the losing question of a race) must reject with something
+* else, or a later genuine failure would be misread as a decline.
+*/
+var AuthorizationDeclinedError = class extends AuthorizationError {
+	constructor(message = "the authorization prompt was declined") {
+		super(message, "DECLINED");
+		this.name = "AuthorizationDeclinedError";
+	}
+};
+/**
+* `ctx.authorization`: a registry of credential-obtaining flows, one attempt at
+* a time per key.
+*/
+var AuthorizationService = class extends Service {
+	/** The commit this seam confirms is a credential-record write, so the store is required, not optional. */
+	static inject = ["credentials"];
+	flows = /* @__PURE__ */ new Map();
+	running = /* @__PURE__ */ new Map();
+	constructor(ctx) {
+		super(ctx, "authorization");
+	}
+	/**
+	* Offer a way to obtain one credential. One flow per key: two plugins
+	* claiming the same key would each write a record in their own format, and
+	* whichever ran last would leave the other reading a payload it cannot parse.
+	*
+	* @param flow - the key it writes, its label, its methods, and its runner.
+	* @returns Disposer that withdraws this flow.
+	* @throws {AuthorizationError} code `DUPLICATE_FLOW` when the key is already claimed.
+	*/
+	registerFlow(flow) {
+		const dispose = this.ctx.effect(function* () {
+			if (this.flows.has(flow.key)) throw new AuthorizationError(`an authorization flow for "${flow.key}" is already registered`, "DUPLICATE_FLOW");
+			this.flows.set(flow.key, flow);
+			yield () => {
+				this.flows.delete(flow.key);
+				this.running.get(flow.key)?.controller.abort();
+			};
+		}.bind(this), "authorization.registerFlow()");
+		return () => void dispose();
+	}
+	/**
+	* Every registered flow, for a surface listing what can be authorized.
+	* @returns one entry per flow, in registration order.
+	*/
+	list() {
+		return [...this.flows.values()].map((flow) => this.entry(flow));
+	}
+	/**
+	* One registered flow.
+	* @param key - the credential record to ask about.
+	* @returns the entry, or undefined when no flow claims that key.
+	*/
+	describe(key) {
+		const flow = this.flows.get(key);
+		return flow === void 0 ? void 0 : this.entry(flow);
+	}
+	/** The public view of one registered flow. */
+	entry(flow) {
+		return {
+			key: flow.key,
+			label: flow.label,
+			methods: flow.methods,
+			inFlight: this.running.has(flow.key)
+		};
+	}
+	/**
+	* Withdraw the attempt running for a key, if any. Separate from the
+	* request's own signal because a request/response transport answers a Cancel
+	* button on a second call, with no handle on the first one's signal.
+	* @param key - the credential record whose attempt should stop.
+	*/
+	cancel(key) {
+		this.running.get(key)?.controller.abort();
+	}
+	/**
+	* Run one attempt to authorize a key, and report how it ended.
+	*
+	* One attempt per key at a time. A second caller is refused rather than
+	* joined: the two would be prompting different humans through the same flow,
+	* and the second would answer questions the first was asked.
+	*
+	* @param request - the key, the method, the surface, and the cancel signal.
+	* @returns `authorized` once the flow's record is committed during this
+	*   attempt and observed, or `cancelled` when the human declined or the
+	*   caller withdrew.
+	* @throws {AuthorizationError} code `NO_FLOW` when nothing claims the key,
+	*   `UNKNOWN_METHOD` when the named method is not one the flow offers,
+	*   `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or
+	*   `NOT_COMMITTED` when the flow resolved without committing a record
+	*   during the attempt.
+	*/
+	async begin(request) {
+		const { key } = request;
+		const flow = this.flows.get(key);
+		if (flow === void 0) throw new AuthorizationError(`no authorization flow is registered for "${key}"`, "NO_FLOW");
+		const method = request.method ?? flow.methods[0].id;
+		if (!flow.methods.some((candidate) => candidate.id === method)) throw new AuthorizationError(`authorization flow for "${key}" offers no method "${method}"`, "UNKNOWN_METHOD");
+		if (this.running.has(key)) throw new AuthorizationError(`an authorization attempt for "${key}" is already running`, "ALREADY_IN_FLIGHT");
+		if (request.signal?.aborted === true) return { status: "cancelled" };
+		const controller = new AbortController();
+		const withdraw = () => {
+			controller.abort(request.signal?.reason);
+		};
+		request.signal?.addEventListener("abort", withdraw, { once: true });
+		this.running.set(key, { controller });
+		let settlement = "failed";
+		try {
+			const outcome = await this.attempt(flow, method, controller.signal, request.interaction);
+			settlement = outcome.status;
+			return outcome;
+		} finally {
+			request.signal?.removeEventListener("abort", withdraw);
+			this.running.delete(key);
+			this.settle(key, settlement);
+		}
+	}
+	/**
+	* Fan `authorization/settled` out with contained listener failures: every
+	* listener runs, and a sync throw or async rejection is logged without
+	* changing the finished attempt's own outcome — except `INVARIANT`-coded
+	* failures, which rethrow after every listener ran. The attempt is already
+	* over and its key released when this fires, so a broken watcher (that
+	* second browser tab) can never turn the caller's settled result into a
+	* failure of its own.
+	*/
+	settle(key, settlement) {
+		let invariantFailure;
+		const args = [
+			"authorization/settled",
+			key,
+			settlement
+		];
+		for (const listener of this.ctx.events.dispatch("emit", args)) try {
+			const returned = listener(key, settlement);
+			if (returned != null && typeof returned.then === "function") Promise.resolve(returned).then(void 0, (error) => {
+				this.warnSettledListenerFailure(key, error);
+			});
+		} catch (error) {
+			if (error?.code === "INVARIANT") {
+				invariantFailure ??= error;
+				continue;
+			}
+			this.warnSettledListenerFailure(key, error);
+		}
+		if (invariantFailure !== void 0) throw invariantFailure;
+	}
+	/** Contained-listener diagnostic shared by the sync and async failure paths. */
+	warnSettledListenerFailure(key, error) {
+		this.ctx.logger.warn("authorization: an authorization/settled listener for \"%s\" failed", key);
+		this.ctx.logger.warn(error);
+	}
+	/** Run the flow, then hold it to its half of the commit contract. */
+	async attempt(flow, method, signal, interaction) {
+		const withdrawn = new Promise((resolve) => {
+			signal.addEventListener("abort", () => {
+				resolve("withdrawn");
+			}, { once: true });
+		});
+		const observed = {
+			declined: false,
+			committed: false
+		};
+		const unwatch = this.ctx.on("credentials/record-updated", (key) => {
+			if (key === flow.key) observed.committed = true;
+		});
+		try {
+			const running = flow.run({
+				method,
+				signal,
+				notify: (notice) => {
+					try {
+						interaction.notify(notice);
+					} catch (error) {
+						this.ctx.logger.warn("authorization: the interaction surface failed to render a notice");
+						this.ctx.logger.warn(error);
+					}
+				},
+				prompt: (prompt) => interaction.prompt(prompt).catch((error) => {
+					if (error instanceof AuthorizationDeclinedError) observed.declined = true;
+					throw error;
+				})
+			});
+			try {
+				if (await Promise.race([running.then(() => "ran"), withdrawn]) === "withdrawn") {
+					running.catch(() => {
+						this.ctx.logger.debug("authorization: withdrawn flow failed after the fact");
+					});
+					return { status: "cancelled" };
+				}
+			} catch (error) {
+				if (signal.aborted || observed.declined) return { status: "cancelled" };
+				throw error;
+			}
+		} finally {
+			unwatch();
+		}
+		if (!observed.committed) throw new AuthorizationError(`authorization flow for "${flow.key}" resolved without committing a credential record in this attempt`, "NOT_COMMITTED");
+		if (!(await this.ctx.credentials.describeRecord(flow.key)).configured) throw new AuthorizationError(`authorization flow for "${flow.key}" deleted its credential record instead of committing one`, "NOT_COMMITTED");
+		return { status: "authorized" };
+	}
+};
+//#endregion
+export { AuthorizationDeclinedError, AuthorizationError, AuthorizationService, AuthorizationService as default };