backstage-plugin-catalog-backend-module-history 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# backstage-plugin-catalog-backend-module-history
 
-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.
+Backstage backend module that records catalog entity changes into a versioned history store.
+
+The default backend feature loader installs both the catalog backend module and the default Postgres `historyStoreServiceRef` factory from `@kunickiaj/catalog-history-backend`.
+
+```ts
+backend.add(import('backstage-plugin-catalog-backend-module-history'));
+```
+
+Advanced storage overrides should register their own `historyStoreServiceRef` factory and import the named module instead of the default loader:
+
+```ts
+backend.add(catalogModuleHistory);
+backend.add(myHistoryStoreServiceFactory);
+```
+
+Provider wrappers should be configured in the same catalog module where the provider is created: depend on `historyStoreServiceRef`, then pass the resolved store into `HistoryRecordingEntityProvider`. The legacy `catalog.history.database` setting remains as a deprecated compatibility path honored by the default store factory, so all consumers of the injected store share the same connection.
+
+## Optional full-to-delta conversion
+
+`HistoryRecordingEntityProvider` defaults to forwarding provider mutations unchanged. With `convertFullToDelta: true`, full snapshots with an existing history baseline become deltas: every incoming entry goes into `added`, with its `locationKey` intact, and history refs missing from the snapshot go into `removed`. The catalog compares each entry's full content and key; the wrapper does not use history etags to filter catalog writes. This preserves key-only changes and content changes even when a provider reuses an etag, but does not avoid comparing unchanged entries.
+
+History still classifies changes using entity etags, so its counts can report an entry as unchanged even when the catalog sees a key or content change. History is best-effort, not a deletion safety check: a missing history ref cannot produce an inferred removal. An empty baseline or a failed baseline read forwards the original full mutation instead.
+
+With `forceFullEvery` configured, the first full after the wrapper starts is forwarded unchanged even when history already has a baseline. Each successfully forwarded full starts the interval, including a fallback full after a history-read failure; rejected catalog writes and native deltas do not reset it. The first full received at or after the interval expires is forwarded unchanged to reconcile against the catalog's own provider refs. This is not a background timer. Keep conversion disabled when deletions must always use the catalog's current provider refs.
+
+### Catalog regression tests
+
+The provider tests include an in-memory SQLite integration with the pinned catalog backend development dependency. Run them from the workspace root with `env CI=1 yarn test packages/catalog-backend-module-history/src/provider --watch=false --runInBand`. They do not require a running catalog or an external database.
+
+For current usage and productization roadmap details, see the [workspace README](../../README.md).

package/bin/reconcile-catalog-history.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Thin shim so npm can wire this up via package.json `bin`. The real work
+// lives in src/bin/reconcile.ts and is built into
+// dist/reconcile-cli.cjs.js by @backstage/cli (declared as an entry point
+// in the package.json `exports` field).
+const { main } = require('../dist/reconcile-cli.cjs.js');
+
+main().catch(err => {
+  process.stderr.write(
+    `error ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+  if (err && err.stack) {
+    process.stderr.write(`${err.stack}\n`);
+  }
+  process.exit(1);
+});

package/config.schema.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "catalog": {
+      "type": "object",
+      "properties": {
+        "history": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Master switch for the catalog history module. Set to false to skip schema bootstrap entirely."
+            },
+            "database": {
+              "type": "object",
+              "properties": {
+                "client": {
+                  "type": "string",
+                  "description": "Knex database client name. Defaults to pg."
+                },
+                "connection": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": {}
+                    }
+                  ],
+                  "description": "Knex connection string or connection object for the history database. Required when the `database` block is present — the default store factory uses it to open the override connection.",
+                  "visibility": "secret",
+                  "deepVisibility": "secret"
+                }
+              },
+              "required": [
+                "connection"
+              ],
+              "description": "Deprecated compatibility database override for history storage.\n\nPrefer registering a custom `historyStoreServiceRef` factory in your backend instead. That lets provider wrappers, processor capture, and scheduled reconciliation all receive the same store through Backstage DI at creation time.\n\nThe default `historyStoreServiceFactory` honors this override for all consumers of `historyStoreServiceRef`, including provider wrappers that inject the same store in their own catalog module."
+            },
+            "provider": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "Enables provider-layer history recording. Defaults to true."
+                }
+              },
+              "description": "Provider-layer capture settings.\n\nIMPORTANT: this key is advisory — the backend module cannot enforce it, because provider wrapping happens in your own backend wiring. You must thread it into the wrapper yourself along with the injected history store, e.g. `new HistoryRecordingEntityProvider({ ..., enabled: config.getOptionalBoolean('catalog.history.provider.enabled') ?? true })`. Setting it in app-config without that wiring has no effect beyond a startup log line."
+            },
+            "processing": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "Enables processor-layer history capture. Defaults to false."
+                }
+              },
+              "description": "Processor-layer capture settings. Defaults to false because processor capture runs once per entity per processing cycle."
+            },
+            "reconciler": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "Enables scheduled in-process reconciliation. Defaults to false."
+                },
+                "schedule": {
+                  "type": "object",
+                  "properties": {
+                    "frequency": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      ],
+                      "description": "Reconciler schedule frequency. Uses Backstage scheduler duration configuration objects, string durations, cron objects, or manual trigger config supported by SchedulerServiceTaskScheduleDefinition."
+                    },
+                    "timeout": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      ],
+                      "description": "Reconciler task timeout. Uses Backstage scheduler duration configuration objects or string durations."
+                    },
+                    "initialDelay": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      ],
+                      "description": "Reconciler initial delay. Uses Backstage scheduler duration configuration objects or string durations."
+                    }
+                  },
+                  "description": "Scheduler configuration for in-process reconciliation. The shape follows Backstage's SchedulerServiceTaskScheduleDefinition config format; omit it to use the default hourly schedule, 10 minute timeout, and 30 second initial delay.\n\nWhen set, `frequency` and `timeout` are both required (Backstage's schedule parser rejects partial definitions at startup); the defaults above apply only when the whole `schedule` key is omitted."
+                }
+              },
+              "description": "In-process reconciler settings. Defaults to disabled. When enabled without an explicit schedule, the task runs hourly with a 10 minute timeout and a 30 second initial delay."
+            }
+          },
+          "description": "Catalog history module configuration."
+        }
+      },
+      "description": "Configuration for catalog history capture and storage."
+    }
+  }
+}

package/dist/index.cjs.js

@@ -0,0 +1,44 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+var catalogHistoryBackend = require('@kunickiaj/catalog-history-backend');
+var catalogModuleHistory = require('./module/catalogModuleHistory.cjs.js');
+var catalogHistoryNode = require('@kunickiaj/catalog-history-node');
+var entityToRow = require('./mapping/entityToRow.cjs.js');
+var HistoryRecordingEntityProvider = require('./provider/HistoryRecordingEntityProvider.cjs.js');
+var HistoryRecordingCatalogProcessor = require('./processor/HistoryRecordingCatalogProcessor.cjs.js');
+var reconcile = require('./reconciler/reconcile.cjs.js');
+var CatalogServiceEntityFetcher = require('./reconciler/CatalogServiceEntityFetcher.cjs.js');
+
+var index = backendPluginApi.createBackendFeatureLoader({
+  loader() {
+    return [catalogHistoryBackend.historyStoreServiceFactory, catalogModuleHistory.catalogModuleHistory];
+  }
+});
+
+Object.defineProperty(exports, "PostgresHistoryStore", {
+  enumerable: true,
+  get: function () { return catalogHistoryBackend.PostgresHistoryStore; }
+});
+Object.defineProperty(exports, "ensureSchema", {
+  enumerable: true,
+  get: function () { return catalogHistoryBackend.ensureSchema; }
+});
+Object.defineProperty(exports, "historyStoreServiceFactory", {
+  enumerable: true,
+  get: function () { return catalogHistoryBackend.historyStoreServiceFactory; }
+});
+exports.catalogModuleHistory = catalogModuleHistory.catalogModuleHistory;
+Object.defineProperty(exports, "RECONCILER_PROVIDER", {
+  enumerable: true,
+  get: function () { return catalogHistoryNode.RECONCILER_PROVIDER; }
+});
+exports.entityToRow = entityToRow.entityToRow;
+exports.HistoryRecordingEntityProvider = HistoryRecordingEntityProvider.HistoryRecordingEntityProvider;
+exports.HistoryRecordingCatalogProcessor = HistoryRecordingCatalogProcessor.HistoryRecordingCatalogProcessor;
+exports.reconcile = reconcile.reconcile;
+exports.CatalogServiceEntityFetcher = CatalogServiceEntityFetcher.CatalogServiceEntityFetcher;
+exports.default = index;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../src/index.ts"],"sourcesContent":["import { createBackendFeatureLoader } from '@backstage/backend-plugin-api';\nimport { historyStoreServiceFactory as defaultHistoryStoreServiceFactory } from '@kunickiaj/catalog-history-backend';\nimport { catalogModuleHistory } from './module/catalogModuleHistory';\n\nexport default createBackendFeatureLoader({\n  loader() {\n    return [defaultHistoryStoreServiceFactory, catalogModuleHistory];\n  },\n});\n\n// Store contracts moved to @kunickiaj/catalog-history-node; re-exported here\n// for compatibility with existing imports.\n/** @deprecated Import from `@kunickiaj/catalog-history-node` instead; these re-exports will be removed in a future release. */\nexport type {\n  CaptureSource,\n  CurrentEtag,\n  CycleInput,\n  EntityRow,\n  HistoryStore,\n  MutationType,\n} from '@kunickiaj/catalog-history-node';\n/** @deprecated Import from `@kunickiaj/catalog-history-node` instead; this re-export will be removed in a future release. */\nexport { RECONCILER_PROVIDER } from '@kunickiaj/catalog-history-node';\n// Storage moved to @kunickiaj/catalog-history-backend; re-exported here for\n// compatibility with existing imports.\n/** @deprecated Import from `@kunickiaj/catalog-history-backend` instead; these re-exports will be removed in a future release. */\nexport {\n  ensureSchema,\n  historyStoreServiceFactory,\n  PostgresHistoryStore,\n} from '@kunickiaj/catalog-history-backend';\nexport { entityToRow } from './mapping/entityToRow';\nexport {\n  HistoryRecordingEntityProvider,\n  type HistoryRecordingEntityProviderOptions,\n} from './provider/HistoryRecordingEntityProvider';\nexport {\n  HistoryRecordingCatalogProcessor,\n  type HistoryRecordingCatalogProcessorOptions,\n} from './processor/HistoryRecordingCatalogProcessor';\nexport { reconcile, type ReconcileOptions } from './reconciler/reconcile';\nexport type { EntityFetcher } from './reconciler/EntityFetcher';\nexport { CatalogServiceEntityFetcher } from './reconciler/CatalogServiceEntityFetcher';\nexport { catalogModuleHistory } from './module/catalogModuleHistory';\n"],"names":["createBackendFeatureLoader","defaultHistoryStoreServiceFactory","catalogModuleHistory"],"mappings":";;;;;;;;;;;;;;AAIA,YAAeA,2CAAA,CAA2B;AAAA,EACxC,MAAA,GAAS;AACP,IAAA,OAAO,CAACC,kDAAmCC,yCAAoB,CAAA;AAAA,EACjE;AACF,CAAC,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,227 @@
+import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
+import { LoggerService, AuthService } from '@backstage/backend-plugin-api';
+import { EntityRow, HistoryStore } from '@kunickiaj/catalog-history-node';
+export { CaptureSource, CurrentEtag, CycleInput, EntityRow, HistoryStore, MutationType, RECONCILER_PROVIDER } from '@kunickiaj/catalog-history-node';
+export { PostgresHistoryStore, ensureSchema, historyStoreServiceFactory } from '@kunickiaj/catalog-history-backend';
+import { Entity } from '@backstage/catalog-model';
+import { EntityProvider, EntityProviderConnection, CatalogProcessor, LocationSpec, CatalogProcessorEmit, CatalogProcessorCache, CatalogService } from '@backstage/plugin-catalog-node';
+
+declare function entityToRow(entity: Entity): EntityRow;
+
+type ForceFullEveryDuration = {
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+};
+type HistoryRecordingEntityProviderOptions = {
+    inner: EntityProvider;
+    store: HistoryStore;
+    logger: LoggerService;
+    /**
+     * When true, full mutations with a history baseline are forwarded as deltas.
+     * Every incoming deferred entry is forwarded unchanged; the catalog compares
+     * its full entity content and location key. History refs are used only to
+     * infer removals, never to filter incoming entries by entity etag.
+     *
+     * Off by default. Combine with {@link forceFullEvery} when you want a
+     * periodic re-convergence safety valve.
+     *
+     * History records the original mutation type using its existing entity-etag
+     * comparison. Its counts can differ from catalog changes. Conversion does not
+     * avoid catalog comparisons for unchanged entries or provide deletion safety.
+     */
+    convertFullToDelta?: boolean;
+    /**
+     * When {@link convertFullToDelta} is on, this controls how often a real
+     * full mutation is allowed through unchanged. Acts as a safety valve so
+     * the catalog can periodically reconcile removals against its own provider
+     * refs when history refs drift. The first full after this wrapper starts is
+     * also forwarded unchanged, even when history already has a baseline.
+     *
+     * If unset, full mutations with a nonempty history baseline are converted.
+     * An empty history baseline always forwards the full mutation as-is.
+     */
+    forceFullEvery?: ForceFullEveryDuration;
+    /**
+     * When false, the wrapper becomes a pure passthrough: mutations are
+     * forwarded to the catalog untouched and nothing is recorded to history.
+     * Lets consumers wire the flag from `catalog.history.provider.enabled`
+     * at backend setup without needing config access inside the wrapper.
+     *
+     * Defaults to true.
+     */
+    enabled?: boolean;
+};
+/**
+ * Wraps an EntityProvider so every applyMutation call is mirrored to a
+ * HistoryStore. The inner provider's normal write to Backstage's catalog
+ * happens first and is unaffected by store failures; history recording is
+ * best-effort and its errors are swallowed.
+ *
+ * Both `full` and `delta` mutations are recorded, one cycle per
+ * applyMutation call. `delta` mutations record the explicit added/removed
+ * lists; full mutations additionally infer deletes for refs present in
+ * history but missing from the incoming entity set.
+ *
+ * Bursty delta coalescing (debounce a burst of webhook events into one
+ * cycle) is deferred to a later phase; today every applyMutation
+ * invocation produces its own cycle.
+ *
+ * When {@link HistoryRecordingEntityProviderOptions.convertFullToDelta} is
+ * set, full mutations are converted to deltas before forwarding to the
+ * catalog, using history refs to infer removals. Incoming entries are never
+ * filtered by history etags, which cannot describe location-key-only changes
+ * or every content change that the catalog detects.
+ */
+declare class HistoryRecordingEntityProvider implements EntityProvider {
+    private readonly inner;
+    private readonly store;
+    private readonly logger;
+    private readonly convertFullToDelta;
+    private readonly forceFullEveryMs?;
+    private readonly enabled;
+    private lastForwardedFullAt?;
+    constructor(options: HistoryRecordingEntityProviderOptions);
+    getProviderName(): string;
+    connect(connection: EntityProviderConnection): Promise<void>;
+    private maybeConvertToDelta;
+    private shouldForceFull;
+    private recordMutation;
+}
+
+type HistoryRecordingCatalogProcessorOptions = {
+    store: HistoryStore;
+    logger: LoggerService;
+    maxBatchSize?: number;
+    flushIntervalMs?: number;
+};
+/**
+ * Records processor-layer catalog history without changing catalog behavior.
+ *
+ * Catalog processors cannot observe deletes; deletion truth comes from the
+ * provider and reconciler layers. Registration order across independently-added
+ * backend modules is also not enforceable, so this layer may observe pre-final
+ * content. The reconciler layer remains the backstop; see
+ * docs/adr/2026-07-01-entity-capture-layers.md.
+ *
+ * The per-cycle `n_unchanged` aggregate is approximate: unchanged
+ * observations never trigger a flush by themselves, so their count is
+ * attributed to the next cycle that records actual changes.
+ */
+declare class HistoryRecordingCatalogProcessor implements CatalogProcessor {
+    private readonly options;
+    private readonly maxBatchSize;
+    private readonly flushIntervalMs;
+    private currentEtags;
+    private currentEtagVersions;
+    private seedPromise;
+    private batchOriginalEtags;
+    private batchOriginalEtagVersions;
+    private inserts;
+    private updates;
+    private unchangedCount;
+    private batchStartedAt;
+    private flushTimer;
+    private flushPromise;
+    constructor(options: HistoryRecordingCatalogProcessorOptions);
+    getProcessorName(): string;
+    postProcessEntity(entity: Entity, _location: LocationSpec, _emit: CatalogProcessorEmit, _cache: CatalogProcessorCache): Promise<Entity>;
+    flush(): Promise<void>;
+    stop(): Promise<void>;
+    private getCurrentEtags;
+    private ensureBatchStarted;
+    private flushBuffered;
+    private bufferLength;
+    private clearFlushTimer;
+}
+
+/**
+ * Minimal interface for fetching the current catalog snapshot. Used by the
+ * reconciler so it can be driven either by Backstage's in-process catalog
+ * service (the default deployment) or by the HTTP CatalogClient (the
+ * external CronJob path).
+ */
+interface EntityFetcher {
+    getEntities(): Promise<Entity[]>;
+}
+
+type ReconcileOptions = {
+    fetcher: EntityFetcher;
+    store: HistoryStore;
+    logger: LoggerService;
+};
+/**
+ * Snapshots the catalog via the EntityFetcher, diffs it against the
+ * reconciler's own previously recorded state, and records a single cycle
+ * attributed to provider='reconciler' / source='reconciler' summarizing
+ * the changes in served catalog truth.
+ *
+ * The baseline is intentionally scoped to source='reconciler'. Etags from
+ * other capture layers are computed over different content (provider rows
+ * over pre-processing envelopes, processing rows over pre-stitch output),
+ * so comparing the served-catalog etag against them would report phantom
+ * updates on every real change. Each source keeps its own baseline; the
+ * first reconcile run therefore records the entire catalog as inserts —
+ * an expected one-time cost, same as first enabling processing capture.
+ *
+ * Records a heartbeat cycle (no row changes) when the served catalog and
+ * the reconciler's baseline agree, so an operator can tell from the
+ * cycles table that the reconciler is running on schedule.
+ */
+declare function reconcile(opts: ReconcileOptions): Promise<void>;
+
+/**
+ * EntityFetcher used by the scheduled in-process reconciler mode. The HTTP
+ * CatalogClient path remains available for the external CLI.
+ */
+declare class CatalogServiceEntityFetcher implements EntityFetcher {
+    private readonly catalog;
+    private readonly auth;
+    constructor(options: {
+        catalog: CatalogService;
+        auth: AuthService;
+    });
+    getEntities(): Promise<Entity[]>;
+}
+
+/**
+ * Backstage backend module for the catalog-history plugin. On init it
+ * resolves the history store from Backstage DI and prepares it for use. When
+ * processor-layer capture is enabled, it also registers a history processor
+ * with the catalog processing extension point.
+ *
+ * Wrapping individual EntityProviders for cycle recording is handled at
+ * backend wiring time via the exported `HistoryRecordingEntityProvider`.
+ *
+ * Reconciliation is opt-in and can be scheduled in-process via Backstage's
+ * scheduler service. The external CLI shim (`bin/reconcile-catalog-history.js`)
+ * also remains available for ad-hoc drift detection or external CronJobs.
+ *
+ * Config (all optional, sensible defaults):
+ *
+ * ```yaml
+ * catalog:
+ *   history:
+ *     enabled: true       # set to false to skip schema bootstrap entirely
+ *     database:           # deprecated compatibility override honored by the default historyStoreServiceFactory
+ *       client: pg
+ *       connection: ${PG_HISTORY_URL}
+ *     provider:
+ *       enabled: true     # gates provider-layer recording wrapper wiring
+ *     processing:
+ *       enabled: false    # opt-in CatalogProcessor capture
+ *     reconciler:
+ *       enabled: false    # opt-in scheduled in-process reconciliation
+ *       schedule:
+ *         frequency: { minutes: 30 }
+ *         timeout: { minutes: 5 }
+ *         initialDelay: { seconds: 30 }
+ * ```
+ */
+declare const catalogModuleHistory: _backstage_backend_plugin_api.BackendFeature;
+
+declare const _default: _backstage_backend_plugin_api.BackendFeature;
+
+export { CatalogServiceEntityFetcher, HistoryRecordingCatalogProcessor, HistoryRecordingEntityProvider, catalogModuleHistory, _default as default, entityToRow, reconcile };
+export type { EntityFetcher, HistoryRecordingCatalogProcessorOptions, HistoryRecordingEntityProviderOptions, ReconcileOptions };