Proposed Changes & Peer Review

Relevant source files

The following files were used as context for generating this wiki page:

• backend/infrahub/proposed_change/models.py
• frontend/app/src/entities/proposed-changes/domain/model/proposed-change.ts
• specs/infp-409-artifact-regen-triggers/plan.md
• specs/ifc-2738-generator-regen-triggers/plan.md
• dev/guidelines/git-workflow.md
• dev/constitution.md

Proposed Changes facilitate a Git-like branching and version control workflow for infrastructure data within Infrahub. This system enables users to isolate modifications, perform peer reviews, and automate the regeneration of dependent artifacts and generators before merging changes into a stable branch. The process ensures data integrity by validating modifications against the active schema and enforcing branch-safe operations across the temporal model.

Sources: dev/constitution.md:16-28, AGENTS.md:7-10

Core Data Models

The Proposed Change system utilizes specific data structures in both the backend and frontend to track definitions and dependencies.

Backend Pipeline Models

The backend uses specialized models to represent artifact and generator definitions during the proposed change lifecycle. These models track which definitions require regeneration based on Git-related file changes.

Model	Key Attributes	Purpose
ProposedChangeArtifactDefinition	dependencies, dependencies_complete	Tracks closures for Jinja2/Python transforms to trigger artifact regeneration.
ProposedChangeGeneratorDefinition	query_id, dependencies, dependencies_complete	Tracks specific queries and file closures to trigger generator execution.

Sources: specs/infp-409-artifact-regen-triggers/plan.md:12-18, specs/ifc-2738-generator-regen-triggers/plan.md:14-22

Frontend Domain Entities

The frontend represents a ProposedChange as an entity with attributes for identification, status tracking, and metadata.

export interface ProposedChange {
  id: string;
  name: string;
  description?: string;
  status: ProposedChangeStatus;
  branch: string;
  createdAt: string;
  updatedAt: string;
}

Sources: frontend/app/src/entities/proposed-changes/domain/model/proposed-change.ts:1-12

Architecture and Data Flow

The Proposed Change architecture relies on a "branch-safe" design where database queries include branch and temporal filters.

Regeneration Logic

When a Proposed Change involves Git modifications, the system evaluates specific predicates against a diff_summary to determine if artifacts or generators must be updated. This prevents unnecessary regeneration (over-regeneration is acceptable, but under-regeneration is prohibited).

This diagram shows the logic flow for determining when a definition must be regenerated based on code or query changes.
Sources: specs/infp-409-artifact-regen-triggers/plan.md:52-58, specs/ifc-2738-generator-regen-triggers/plan.md:65-72

Predicate Functions

Three primary predicates gate the regeneration process:

1. _query_changed: Checks if the associated query_id was modified.
2. _definition_changed: Checks if the CoreArtifactDefinition or CoreGeneratorDefinition node ID was modified.
3. _transform_changed: Checks if the underlying Python or Jinja2 transformation code in the repository closure was modified.

Sources: specs/infp-409-artifact-regen-triggers/plan.md:14-16, specs/ifc-2738-generator-regen-triggers/plan.md:14-16

Peer Review Workflow

The peer review workflow follows a structured Git-based pattern. Users create feature branches from develop, submit their proposed changes for review, and merge back upon approval.

Workflow Stages

1. Branch Creation: Create a branch with the naming pattern <initials>-<short-description>.
2. Modification: Commit changes using conventional commit formats (e.g., feat:, fix:).
3. Automated Validation: The system runs refresh_artifacts and validate_artifacts_generation tasks. These tasks utilize the repo file diff, which is decoupled from sync_with_git to support CoreReadOnlyRepository.
4. Review: Peer review is conducted on the proposed change.
5. Merge: Changes are merged into the target branch.

This sequence diagram illustrates the lifecycle of a proposed change from branch creation to validation and eventual merging.
Sources: dev/guidelines/git-workflow.md:1-20, specs/infp-409-artifact-regen-triggers/plan.md:14-22

Integrity and Security

The Proposed Change system adheres to strict integrity principles defined in the project constitution:

• Schema-Driven Integrity: All writes must validate against the active schema for the target branch.
• Parameterization: All database queries generated by the proposed change pipeline use parameterized Cypher ($param) to prevent injection.
• Authorization: Authorization is checked at the API layer, ensuring that id-driven mutations in proposed changes respect branch scoping.

Sources: dev/constitution.md:12-25, specs/archive/002-user-facing-schema/critiques/critique-20260701-120657.md:46-50

Summary

Proposed Changes & Peer Review form the foundation of version-controlled infrastructure management in Infrahub. By leveraging Git-like branching and precise regeneration triggers for artifacts and generators, the system ensures that changes are isolated, validated, and reviewed. This architecture maintains data integrity and operational safety across complex infrastructure topologies.