From cbc174c5ba6ff2ccfa3505ff08f9b524550c27db Mon Sep 17 00:00:00 2001 From: fullsend-code <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Tue, 15 Sep 2026 21:27:12 +0000 Subject: [PATCH 1/4] docs(#4788): add entity provider design concepts to AGENTS.md Add an "Entity Provider Design Concepts" section to the ai-integrations workspace AGENTS.md. This provides specification-review-level guidance for entity provider OpenSpec files, covering: - Entity identity and collision handling for (kind, namespace, name) tuples across multiple providers - The distinction between locationKey (mutation ownership) and backstage.io/managed-by-location (provenance annotation) - Full mutation pruning semantics when previously valid entities become unmappable - Annotation data contracts and round-trip guarantees when projecting upstream fields into catalog annotations These concepts address review blind spots identified in PR #4667 where human reviewers caught four specification design issues the review agent missed due to lacking domain context about Backstage entity lifecycle concepts. Complements #4781 which covers implementation-level entity provider conventions (source-location format, timeouts, size limits, pagination). Closes #4788 Assisted-by: claude-opus-4-6 --- workspaces/ai-integrations/AGENTS.md | 41 ++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/workspaces/ai-integrations/AGENTS.md b/workspaces/ai-integrations/AGENTS.md index df77ae5588c..49ed463b954 100644 --- a/workspaces/ai-integrations/AGENTS.md +++ b/workspaces/ai-integrations/AGENTS.md @@ -165,6 +165,47 @@ The upstream PR number must be documented in the changeset description or linked issue so reviewers (human and automated) can verify the upstream alignment. +## Entity Provider Design Concepts + +Reference for reviewing and authoring entity provider specifications +(OpenSpec files under `openspec/changes/`). + +### Entity identity + +Backstage catalog entities are uniquely identified by `(kind, namespace, +name)`. When multiple providers can emit the same identity tuple, the +specification must state how the provider constructs each component and +what happens when a collision with another provider is possible. If the +provider uses caller-supplied prefixes for scoping, the specification +should define the default and document the collision behavior. + +### locationKey vs managed-by-location + +These are distinct mechanisms -- do not conflate them: +- **`locationKey`** is set on the entity mutation and determines which + provider owns the entity for processing. The catalog uses it to scope + updates and deletions. +- **`backstage.io/managed-by-location`** is an annotation on the entity + showing provenance (which location ingested it). It is informational. + +### Full mutation semantics + +`type: 'full'` mutations replace the entire set of entities owned by +the provider's locationKey. An entity absent from the next full mutation +is pruned from the catalog. Specifications must explicitly state what +happens when a previously valid entity becomes unmappable (transient +failure, schema drift): is it pruned or retained from the last +successful sync? If retained, how is the stale state communicated? + +### Annotation data contracts + +When a specification promises that upstream fields are projected into +catalog annotations, it creates a round-trip contract: the original +value should be recoverable. URL normalization, truncation, or lossy +transforms can violate this. Specifications should state which fields +are preserved exactly and which are normalized, and provide a separate +annotation for the original value when normalization is lossy. + ## PR Conventions - All commits must have an `Assisted-by: ` footer below the sign offs From 637fd2ce3c4b6fe981fed48f459c438eb88811d3 Mon Sep 17 00:00:00 2001 From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Tue, 15 Sep 2026 21:55:56 +0000 Subject: [PATCH 2/4] fix: replace double-hyphen with em dash in AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace '--' with '—' on line 184 to match the established em dash convention used throughout the file. Addresses human review feedback on #4792 --- workspaces/ai-integrations/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/workspaces/ai-integrations/AGENTS.md b/workspaces/ai-integrations/AGENTS.md index 49ed463b954..6bf7d0daf3a 100644 --- a/workspaces/ai-integrations/AGENTS.md +++ b/workspaces/ai-integrations/AGENTS.md @@ -181,7 +181,7 @@ should define the default and document the collision behavior. ### locationKey vs managed-by-location -These are distinct mechanisms -- do not conflate them: +These are distinct mechanisms — do not conflate them: - **`locationKey`** is set on the entity mutation and determines which provider owns the entity for processing. The catalog uses it to scope updates and deletions. From 23e615d32c7354cc7b74b6ef85a0c655e7223a18 Mon Sep 17 00:00:00 2001 From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Tue, 15 Sep 2026 22:20:24 +0000 Subject: [PATCH 3/4] style: run prettier on AGENTS.md to fix formatting check Add blank line between paragraph and list in the locationKey vs managed-by-location section, required by prettier markdown formatting. Addresses review feedback on #4792 --- workspaces/ai-integrations/AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/workspaces/ai-integrations/AGENTS.md b/workspaces/ai-integrations/AGENTS.md index 6bf7d0daf3a..a2b8da1e65d 100644 --- a/workspaces/ai-integrations/AGENTS.md +++ b/workspaces/ai-integrations/AGENTS.md @@ -182,6 +182,7 @@ should define the default and document the collision behavior. ### locationKey vs managed-by-location These are distinct mechanisms — do not conflate them: + - **`locationKey`** is set on the entity mutation and determines which provider owns the entity for processing. The catalog uses it to scope updates and deletions. From 24d068c0ee4397a4e6b08f418080bded5112f61b Mon Sep 17 00:00:00 2001 From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Tue, 15 Sep 2026 22:57:05 +0000 Subject: [PATCH 4/4] fix: format heading with backticks to match convention in PR #4792 Wrap `locationKey` and `managed-by-location` in backticks in the section heading to match the established convention used by other headings in this file (e.g., `targetPluginId`, `getOptionalString()`). Addresses review feedback on #4792 Assisted-by: claude-opus-4-6 --- workspaces/ai-integrations/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/workspaces/ai-integrations/AGENTS.md b/workspaces/ai-integrations/AGENTS.md index a2b8da1e65d..838aea46596 100644 --- a/workspaces/ai-integrations/AGENTS.md +++ b/workspaces/ai-integrations/AGENTS.md @@ -179,7 +179,7 @@ what happens when a collision with another provider is possible. If the provider uses caller-supplied prefixes for scoping, the specification should define the default and document the collision behavior. -### locationKey vs managed-by-location +### `locationKey` vs `managed-by-location` These are distinct mechanisms — do not conflate them: