@contractspec/lib.contracts 1.44.0

package/dist/regenerator/executor.d.ts

@@ -0,0 +1,70 @@
+import { ProposalAction, RegenerationContext, SpecChangeProposal } from "./types.js";
+
+//#region src/regenerator/executor.d.ts
+type ExecutionStatus = 'success' | 'skipped' | 'failed';
+interface ActionExecutionResult {
+  index: number;
+  action: ProposalAction;
+  status: ExecutionStatus;
+  startedAt: Date;
+  finishedAt: Date;
+  reason?: string;
+  error?: Error;
+  output?: unknown;
+}
+interface ProposalExecutionResult {
+  proposalId: string;
+  contextId: string;
+  startedAt: Date;
+  finishedAt: Date;
+  status: 'success' | 'partial' | 'failed';
+  actions: ActionExecutionResult[];
+}
+type UpdateBlueprintAction = Extract<ProposalAction, {
+  kind: 'update_blueprint';
+}>;
+type UpdateTenantConfigAction = Extract<ProposalAction, {
+  kind: 'update_tenant_config';
+}>;
+type RunTestsAction = Extract<ProposalAction, {
+  kind: 'run_tests';
+}>;
+type RunMigrationsAction = Extract<ProposalAction, {
+  kind: 'run_migrations';
+}>;
+type TriggerRegenerationAction = Extract<ProposalAction, {
+  kind: 'trigger_regeneration';
+}>;
+interface BlueprintUpdater {
+  applyBlueprintUpdate(context: RegenerationContext, proposal: SpecChangeProposal, action: UpdateBlueprintAction): Promise<unknown>;
+}
+interface TenantConfigUpdater {
+  applyTenantConfigUpdate(context: RegenerationContext, proposal: SpecChangeProposal, action: UpdateTenantConfigAction): Promise<unknown>;
+}
+interface TestExecutor {
+  runTests(context: RegenerationContext, proposal: SpecChangeProposal, action: RunTestsAction): Promise<unknown>;
+}
+interface MigrationExecutor {
+  runMigrations(context: RegenerationContext, proposal: SpecChangeProposal, action: RunMigrationsAction): Promise<unknown>;
+}
+interface RegenerationTrigger {
+  triggerRegeneration(context: RegenerationContext, proposal: SpecChangeProposal, action: TriggerRegenerationAction): Promise<unknown>;
+}
+interface ProposalExecutorOptions {
+  dryRun?: boolean;
+}
+interface ProposalExecutorDeps {
+  blueprintUpdater?: BlueprintUpdater;
+  tenantConfigUpdater?: TenantConfigUpdater;
+  testExecutor?: TestExecutor;
+  migrationExecutor?: MigrationExecutor;
+  regenerationTrigger?: RegenerationTrigger;
+}
+declare class ProposalExecutor {
+  private readonly deps;
+  constructor(deps?: ProposalExecutorDeps);
+  execute(context: RegenerationContext, proposal: SpecChangeProposal, options?: ProposalExecutorOptions): Promise<ProposalExecutionResult>;
+  private executeAction;
+}
+//#endregion
+export { ActionExecutionResult, BlueprintUpdater, ExecutionStatus, MigrationExecutor, ProposalExecutionResult, ProposalExecutor, ProposalExecutorDeps, ProposalExecutorOptions, RegenerationTrigger, RunMigrationsAction, RunTestsAction, TenantConfigUpdater, TestExecutor, TriggerRegenerationAction, UpdateBlueprintAction, UpdateTenantConfigAction };

package/dist/regenerator/executor.js

@@ -0,0 +1,86 @@
+//#region src/regenerator/executor.ts
+var ProposalExecutor = class {
+	constructor(deps = {}) {
+		this.deps = deps;
+	}
+	async execute(context, proposal, options = {}) {
+		const startedAt = /* @__PURE__ */ new Date();
+		const actionResults = [];
+		for (const [index, action] of proposal.actions.entries()) {
+			const result = await this.executeAction({
+				index,
+				action,
+				context,
+				proposal,
+				options
+			});
+			actionResults.push(result);
+		}
+		const finishedAt = /* @__PURE__ */ new Date();
+		const summaryStatus = summarizeStatus(actionResults);
+		return {
+			proposalId: proposal.id,
+			contextId: context.id,
+			startedAt,
+			finishedAt,
+			status: summaryStatus,
+			actions: actionResults
+		};
+	}
+	async executeAction({ index, action, context, proposal, options }) {
+		const startedAt = /* @__PURE__ */ new Date();
+		const dryRun = options.dryRun ?? false;
+		const complete = (status, params = {}) => ({
+			index,
+			action,
+			status,
+			startedAt,
+			finishedAt: /* @__PURE__ */ new Date(),
+			reason: params.reason,
+			output: params.output,
+			error: params.error
+		});
+		if (dryRun) return complete("skipped", { reason: "dry_run" });
+		try {
+			switch (action.kind) {
+				case "update_blueprint": {
+					const updater = this.deps.blueprintUpdater;
+					if (!updater) return complete("skipped", { reason: "missing_blueprint_updater" });
+					return complete("success", { output: await updater.applyBlueprintUpdate(context, proposal, action) });
+				}
+				case "update_tenant_config": {
+					const updater = this.deps.tenantConfigUpdater;
+					if (!updater) return complete("skipped", { reason: "missing_tenant_config_updater" });
+					return complete("success", { output: await updater.applyTenantConfigUpdate(context, proposal, action) });
+				}
+				case "run_tests": {
+					const executor = this.deps.testExecutor;
+					if (!executor) return complete("skipped", { reason: "missing_test_executor" });
+					return complete("success", { output: await executor.runTests(context, proposal, action) });
+				}
+				case "run_migrations": {
+					const executor = this.deps.migrationExecutor;
+					if (!executor) return complete("skipped", { reason: "missing_migration_executor" });
+					return complete("success", { output: await executor.runMigrations(context, proposal, action) });
+				}
+				case "trigger_regeneration": {
+					const trigger = this.deps.regenerationTrigger;
+					if (!trigger) return complete("skipped", { reason: "missing_regeneration_trigger" });
+					return complete("success", { output: await trigger.triggerRegeneration(context, proposal, action) });
+				}
+				default: return complete("skipped", { reason: "unknown_action" });
+			}
+		} catch (error) {
+			return complete("failed", { error: error instanceof Error ? error : new Error(String(error)) });
+		}
+	}
+};
+function summarizeStatus(actionResults) {
+	if (actionResults.some((result) => result.status === "failed")) return "failed";
+	if (actionResults.some((result) => result.status === "success") && actionResults.some((result) => result.status === "skipped")) return "partial";
+	if (actionResults.every((result) => result.status === "skipped")) return "partial";
+	return "success";
+}
+
+//#endregion
+export { ProposalExecutor };

package/dist/regenerator/index.d.ts

@@ -0,0 +1,7 @@
+import { BehaviorSignal, BehaviorSignalEnvelope, ErrorSignal, ErrorSignalEnvelope, ProposalAction, ProposalBlocker, ProposalConfidence, ProposalSink, ProposalTarget, RegenerationContext, RegenerationRule, RegeneratorSignal, SpecChangeProposal, TelemetrySignal, TelemetrySignalEnvelope } from "./types.js";
+import { BehaviorSignalProvider, ErrorSignalProvider, SignalAdapters, TelemetrySignalProvider } from "./adapters.js";
+import { RegeneratorOptions, RegeneratorService } from "./service.js";
+import { ActionExecutionResult, BlueprintUpdater, ExecutionStatus, MigrationExecutor, ProposalExecutionResult, ProposalExecutor, ProposalExecutorDeps, ProposalExecutorOptions, RegenerationTrigger, RunMigrationsAction, RunTestsAction, TenantConfigUpdater, TestExecutor, TriggerRegenerationAction, UpdateBlueprintAction, UpdateTenantConfigAction } from "./executor.js";
+import { behaviorToEnvelope, errorToEnvelope, telemetryToEnvelope } from "./utils.js";
+import { ExecutorProposalSink, ExecutorResultPayload, ExecutorSinkLogger, ExecutorSinkOptions } from "./sinks.js";
+export { ActionExecutionResult, BehaviorSignal, BehaviorSignalEnvelope, BehaviorSignalProvider, BlueprintUpdater, ErrorSignal, ErrorSignalEnvelope, ErrorSignalProvider, ExecutionStatus, ExecutorProposalSink, ExecutorResultPayload, ExecutorSinkLogger, ExecutorSinkOptions, MigrationExecutor, ProposalAction, ProposalBlocker, ProposalConfidence, ProposalExecutionResult, ProposalExecutor, ProposalExecutorDeps, ProposalExecutorOptions, ProposalSink, ProposalTarget, RegenerationContext, RegenerationRule, RegenerationTrigger, RegeneratorOptions, RegeneratorService, RegeneratorSignal, RunMigrationsAction, RunTestsAction, SignalAdapters, SpecChangeProposal, TelemetrySignal, TelemetrySignalEnvelope, TelemetrySignalProvider, TenantConfigUpdater, TestExecutor, TriggerRegenerationAction, UpdateBlueprintAction, UpdateTenantConfigAction, behaviorToEnvelope, errorToEnvelope, telemetryToEnvelope };

package/dist/regenerator/index.js

@@ -0,0 +1,6 @@
+import { behaviorToEnvelope, errorToEnvelope, telemetryToEnvelope } from "./utils.js";
+import { RegeneratorService } from "./service.js";
+import { ProposalExecutor } from "./executor.js";
+import { ExecutorProposalSink } from "./sinks.js";
+
+export { ExecutorProposalSink, ProposalExecutor, RegeneratorService, behaviorToEnvelope, errorToEnvelope, telemetryToEnvelope };

package/dist/regenerator/service.d.ts

@@ -0,0 +1,33 @@
+import { ProposalSink, RegenerationContext, RegenerationRule } from "./types.js";
+import { SignalAdapters } from "./adapters.js";
+
+//#region src/regenerator/service.d.ts
+interface RegeneratorOptions {
+  contexts: RegenerationContext[];
+  adapters: SignalAdapters;
+  rules: RegenerationRule[];
+  sink: ProposalSink;
+  pollIntervalMs?: number;
+  batchDurationMs?: number;
+  clock?: () => Date;
+}
+declare class RegeneratorService {
+  private readonly options;
+  private readonly contexts;
+  private readonly lastPoll;
+  private timer?;
+  private running;
+  private readonly pollInterval;
+  private readonly batchDuration;
+  private readonly clock;
+  constructor(options: RegeneratorOptions);
+  start(): void;
+  stop(): void;
+  runOnce(): Promise<void>;
+  private tick;
+  private evaluateContext;
+  private collectSignals;
+  private flushProposals;
+}
+//#endregion
+export { RegeneratorOptions, RegeneratorService };

package/dist/regenerator/service.js

@@ -0,0 +1,93 @@
+import { behaviorToEnvelope, errorToEnvelope, telemetryToEnvelope } from "./utils.js";
+
+//#region src/regenerator/service.ts
+/** Cross-platform delay that works in browser and Node.js */
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const DEFAULT_POLL_INTERVAL = 6e4;
+const DEFAULT_BATCH_DURATION = 5 * 6e4;
+var RegeneratorService = class {
+	contexts;
+	lastPoll = /* @__PURE__ */ new Map();
+	timer;
+	running = false;
+	pollInterval;
+	batchDuration;
+	clock;
+	constructor(options) {
+		this.options = options;
+		this.contexts = new Map(options.contexts.map((ctx) => [ctx.id, ctx]));
+		this.pollInterval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL;
+		this.batchDuration = options.batchDurationMs ?? DEFAULT_BATCH_DURATION;
+		this.clock = options.clock ?? (() => /* @__PURE__ */ new Date());
+		if (this.options.rules.length === 0) throw new Error("RegeneratorService requires at least one rule");
+	}
+	start() {
+		if (this.running) return;
+		this.running = true;
+		this.tick();
+		this.timer = setInterval(() => {
+			this.tick();
+		}, this.pollInterval);
+	}
+	stop() {
+		if (!this.running) return;
+		this.running = false;
+		if (this.timer) {
+			clearInterval(this.timer);
+			this.timer = void 0;
+		}
+	}
+	async runOnce() {
+		await this.tick();
+	}
+	async tick() {
+		const now = this.clock();
+		const sinceDefault = new Date(now.getTime() - this.batchDuration);
+		for (const context of this.contexts.values()) {
+			const last = this.lastPoll.get(context.id) ?? sinceDefault;
+			await this.evaluateContext(context, last, now);
+			this.lastPoll.set(context.id, now);
+		}
+	}
+	async evaluateContext(context, since, until) {
+		const signals = await this.collectSignals(context, since, until);
+		if (signals.length === 0) return;
+		for (const rule of this.options.rules) {
+			let proposals = [];
+			try {
+				proposals = await rule.evaluate(context, signals);
+			} catch (error) {
+				console.error(`[regenerator] rule ${rule.id} failed`, error instanceof Error ? error : new Error(String(error)));
+				continue;
+			}
+			await this.flushProposals(context, proposals);
+		}
+	}
+	async collectSignals(context, since, until) {
+		const envelopes = [];
+		const { adapters } = this.options;
+		if (adapters.telemetry) {
+			const telemetrySignals = await adapters.telemetry.pollTelemetry(context, since, until);
+			envelopes.push(...telemetrySignals.map((signal) => telemetryToEnvelope(context.id, signal, this.clock)));
+		}
+		if (adapters.errors) {
+			const errorSignals = await adapters.errors.pollErrors(context, since, until);
+			envelopes.push(...errorSignals.map((signal) => errorToEnvelope(context.id, signal, this.clock)));
+		}
+		if (adapters.behavior) {
+			const behaviorSignals = await adapters.behavior.pollBehavior(context, since, until);
+			envelopes.push(...behaviorSignals.map((signal) => behaviorToEnvelope(context.id, signal, this.clock)));
+		}
+		return envelopes;
+	}
+	async flushProposals(context, proposals) {
+		for (const proposal of proposals) {
+			if (proposal.signalIds.length === 0) continue;
+			await this.options.sink.submit(context, proposal);
+			if (proposals.length > 10) await delay(0);
+		}
+	}
+};
+
+//#endregion
+export { RegeneratorService };

package/dist/regenerator/sinks.d.ts

@@ -0,0 +1,26 @@
+import { ProposalSink, RegenerationContext, SpecChangeProposal } from "./types.js";
+import { ProposalExecutionResult, ProposalExecutor } from "./executor.js";
+
+//#region src/regenerator/sinks.d.ts
+interface ExecutorResultPayload {
+  context: RegenerationContext;
+  proposal: SpecChangeProposal;
+  result: ProposalExecutionResult;
+}
+interface ExecutorSinkLogger {
+  info?: (message: string, meta?: Record<string, unknown>) => void;
+  error?: (message: string, error: Error, meta?: Record<string, unknown>) => void;
+}
+interface ExecutorSinkOptions {
+  dryRun?: boolean;
+  onResult?: (payload: ExecutorResultPayload) => void | Promise<void>;
+  logger?: ExecutorSinkLogger;
+}
+declare class ExecutorProposalSink implements ProposalSink {
+  private readonly executor;
+  private readonly options;
+  constructor(executor: ProposalExecutor, options?: ExecutorSinkOptions);
+  submit(context: RegenerationContext, proposal: SpecChangeProposal): Promise<void>;
+}
+//#endregion
+export { ExecutorProposalSink, ExecutorResultPayload, ExecutorSinkLogger, ExecutorSinkOptions };

package/dist/regenerator/sinks.js

@@ -0,0 +1,32 @@
+//#region src/regenerator/sinks.ts
+var ExecutorProposalSink = class {
+	constructor(executor, options = {}) {
+		this.executor = executor;
+		this.options = options;
+	}
+	async submit(context, proposal) {
+		const dryRun = this.options.dryRun ?? false;
+		try {
+			const result = await this.executor.execute(context, proposal, { dryRun });
+			if (this.options.logger?.info) this.options.logger.info("[regenerator] proposal executed", {
+				proposalId: proposal.id,
+				contextId: context.id,
+				status: result.status
+			});
+			if (this.options.onResult) await this.options.onResult({
+				context,
+				proposal,
+				result
+			});
+		} catch (error) {
+			if (this.options.logger?.error) this.options.logger.error("[regenerator] proposal execution failed", error instanceof Error ? error : new Error(String(error)), {
+				proposalId: proposal.id,
+				contextId: context.id
+			});
+			throw error instanceof Error ? error : new Error(String(error));
+		}
+	}
+};
+
+//#endregion
+export { ExecutorProposalSink };

package/dist/regenerator/types.d.ts

@@ -0,0 +1,107 @@
+import { TelemetrySpec } from "../telemetry/spec.js";
+import { AppBlueprintSpec, TenantAppConfig } from "../app-config/spec.js";
+import { ResolvedAppConfig } from "../app-config/runtime.js";
+
+//#region src/regenerator/types.d.ts
+type RegeneratorSignal = TelemetrySignalEnvelope | ErrorSignalEnvelope | BehaviorSignalEnvelope;
+interface TelemetrySignalEnvelope {
+  type: 'telemetry';
+  contextId: string;
+  signal: TelemetrySignal;
+}
+interface TelemetrySignal {
+  eventName: string;
+  eventVersion: number;
+  count: number;
+  windowStart: Date;
+  windowEnd: Date;
+  anomalyScore?: number;
+  classification?: 'normal' | 'warning' | 'critical';
+  metadata?: Record<string, unknown>;
+  telemetrySpec?: TelemetrySpec;
+}
+interface ErrorSignalEnvelope {
+  type: 'error';
+  contextId: string;
+  signal: ErrorSignal;
+}
+interface ErrorSignal {
+  id: string;
+  classification: 'runtime' | 'policy' | 'workflow' | 'unknown';
+  message: string;
+  occurredAt: Date;
+  count: number;
+  metadata?: Record<string, unknown>;
+}
+interface BehaviorSignalEnvelope {
+  type: 'behavior';
+  contextId: string;
+  signal: BehaviorSignal;
+}
+interface BehaviorSignal {
+  feature: string;
+  metric: 'usage' | 'conversion' | 'latency' | 'custom';
+  value: number;
+  baseline?: number;
+  windowStart: Date;
+  windowEnd: Date;
+  metadata?: Record<string, unknown>;
+}
+interface SpecChangeProposal {
+  id: string;
+  title: string;
+  summary: string;
+  confidence: ProposalConfidence;
+  rationale: string[];
+  target: ProposalTarget;
+  diff?: string;
+  actions: ProposalAction[];
+  blockers?: ProposalBlocker[];
+  createdAt: Date;
+  signalIds: string[];
+}
+type ProposalConfidence = 'low' | 'medium' | 'high';
+interface ProposalTarget {
+  specType: 'workflow' | 'capability' | 'policy' | 'dataView' | 'telemetry' | 'experiment' | 'theme' | 'unknown';
+  reference: {
+    key: string;
+    version?: number;
+  };
+  tenantScoped?: boolean;
+}
+type ProposalAction = {
+  kind: 'update_blueprint';
+  summary: string;
+} | {
+  kind: 'update_tenant_config';
+  summary: string;
+} | {
+  kind: 'run_tests';
+  tests: string[];
+} | {
+  kind: 'run_migrations';
+  migrations: string[];
+} | {
+  kind: 'trigger_regeneration';
+  summary?: string;
+};
+interface ProposalBlocker {
+  description: string;
+  kind: 'missing_context' | 'insufficient_data' | 'user_feedback' | 'manual_review';
+}
+interface RegenerationContext {
+  id: string;
+  blueprint: AppBlueprintSpec;
+  tenantConfig: TenantAppConfig;
+  resolved: ResolvedAppConfig;
+}
+interface RegenerationRule {
+  readonly id: string;
+  readonly description: string;
+  evaluate(context: RegenerationContext, signals: RegeneratorSignal[]): Promise<SpecChangeProposal[]>;
+}
+interface ProposalSink {
+  submit(context: RegenerationContext, proposal: SpecChangeProposal): Promise<void>;
+}
+//#endregion
+export { BehaviorSignal, BehaviorSignalEnvelope, ErrorSignal, ErrorSignalEnvelope, ProposalAction, ProposalBlocker, ProposalConfidence, ProposalSink, ProposalTarget, RegenerationContext, RegenerationRule, RegeneratorSignal, SpecChangeProposal, TelemetrySignal, TelemetrySignalEnvelope };

package/dist/regenerator/utils.d.ts

@@ -0,0 +1,9 @@
+import { BehaviorSignal, BehaviorSignalEnvelope, ErrorSignal, ErrorSignalEnvelope, TelemetrySignal, TelemetrySignalEnvelope } from "./types.js";
+
+//#region src/regenerator/utils.d.ts
+type Clock = () => Date;
+declare function telemetryToEnvelope(contextId: string, signal: TelemetrySignal, clock: Clock): TelemetrySignalEnvelope;
+declare function errorToEnvelope(contextId: string, signal: ErrorSignal, clock: Clock): ErrorSignalEnvelope;
+declare function behaviorToEnvelope(contextId: string, signal: BehaviorSignal, clock: Clock): BehaviorSignalEnvelope;
+//#endregion
+export { behaviorToEnvelope, errorToEnvelope, telemetryToEnvelope };

package/dist/regenerator/utils.js

@@ -0,0 +1,51 @@
+//#region src/regenerator/utils.ts
+function telemetryToEnvelope(contextId, signal, clock) {
+	return {
+		type: "telemetry",
+		contextId,
+		signal: normalizeTelemetryDates(signal, clock)
+	};
+}
+function errorToEnvelope(contextId, signal, clock) {
+	return {
+		type: "error",
+		contextId,
+		signal: normalizeErrorDates(signal, clock)
+	};
+}
+function behaviorToEnvelope(contextId, signal, clock) {
+	return {
+		type: "behavior",
+		contextId,
+		signal: normalizeBehaviorDates(signal, clock)
+	};
+}
+function normalizeTelemetryDates(signal, clock) {
+	return {
+		...signal,
+		windowStart: toDate(signal.windowStart, clock),
+		windowEnd: toDate(signal.windowEnd, clock)
+	};
+}
+function normalizeErrorDates(signal, clock) {
+	return {
+		...signal,
+		occurredAt: toDate(signal.occurredAt, clock)
+	};
+}
+function normalizeBehaviorDates(signal, clock) {
+	return {
+		...signal,
+		windowStart: toDate(signal.windowStart, clock),
+		windowEnd: toDate(signal.windowEnd, clock)
+	};
+}
+function toDate(value, clock) {
+	if (value instanceof Date) return value;
+	const parsed = new Date(value);
+	if (Number.isNaN(parsed.getTime())) return clock();
+	return parsed;
+}
+
+//#endregion
+export { behaviorToEnvelope, errorToEnvelope, telemetryToEnvelope };

package/dist/registry-utils.d.ts

@@ -0,0 +1,106 @@
+import { Stability } from "./ownership.js";
+
+//#region src/registry-utils.d.ts
+
+/**
+ * Filter criteria for registry items.
+ * All criteria are optional and combined with AND logic.
+ */
+interface RegistryFilter {
+  /** Filter by tags (item must have at least one matching tag) */
+  tags?: string[];
+  /** Filter by owners (item must have at least one matching owner) */
+  owners?: string[];
+  /** Filter by stability levels */
+  stability?: Stability[];
+  /** Filter by domain (first segment of name) */
+  domain?: string;
+  /** Filter by key pattern (glob or regex) */
+  keyPattern?: string;
+}
+/**
+ * Item with standard metadata for filtering.
+ */
+interface FilterableItem {
+  meta: {
+    key?: string;
+    tags?: string[];
+    owners?: string[];
+    stability?: Stability;
+    domain?: string;
+  };
+}
+/**
+ * Grouping key function type.
+ */
+type GroupKeyFn<T> = (item: T) => string;
+/**
+ * Grouped items result.
+ */
+interface GroupedItems<T> {
+  key: string;
+  items: T[];
+}
+/**
+ * Pre-built grouping strategies for common use cases.
+ */
+declare const GroupingStrategies: {
+  /**
+   * Group by first tag.
+   */
+  byTag: <T extends FilterableItem>(item: T) => string;
+  /**
+   * Group by all tags (item appears in multiple groups).
+   */
+  byAllTags: <T extends FilterableItem>(item: T) => string[];
+  /**
+   * Group by first owner.
+   */
+  byOwner: <T extends FilterableItem>(item: T) => string;
+  /**
+   * Group by domain (first segment of name).
+   */
+  byDomain: <T extends FilterableItem>(item: T) => string;
+  /**
+   * Group by stability level.
+   */
+  byStability: <T extends FilterableItem>(item: T) => string;
+  /**
+   * Create URL path grouping strategy with configurable depth.
+   */
+  byUrlPath: (level: number) => (item: {
+    path?: string;
+  }) => string;
+};
+/**
+ * Filter items by criteria.
+ * All criteria are combined with AND logic.
+ */
+declare function filterBy<T extends FilterableItem>(items: T[], filter: RegistryFilter): T[];
+/**
+ * Group items by key function.
+ */
+declare function groupBy<T>(items: T[], keyFn: GroupKeyFn<T>): Map<string, T[]>;
+/**
+ * Group items by key function, returning array format.
+ */
+declare function groupByToArray<T>(items: T[], keyFn: GroupKeyFn<T>): GroupedItems<T>[];
+/**
+ * Group items where one item can belong to multiple groups.
+ * Useful for byAllTags grouping.
+ */
+declare function groupByMultiple<T>(items: T[], keysFn: (item: T) => string[]): Map<string, T[]>;
+/**
+ * Get unique tags from a collection of items.
+ */
+declare function getUniqueTags<T extends FilterableItem>(items: T[]): string[];
+/**
+ * Get unique owners from a collection of items.
+ */
+declare function getUniqueOwners<T extends FilterableItem>(items: T[]): string[];
+/**
+ * Get unique domains from a collection of items.
+ */
+declare function getUniqueDomains<T extends FilterableItem>(items: T[]): string[];
+//#endregion
+export { FilterableItem, GroupKeyFn, GroupedItems, GroupingStrategies, RegistryFilter, filterBy, getUniqueDomains, getUniqueOwners, getUniqueTags, groupBy, groupByMultiple, groupByToArray };