Chore/1876 rebase pending revisions

app/schema/schema.graphql

@@ -50871,6 +50871,32 @@ input JSONFilter {
   notIn: [JSON!]
 }
 
+"""All input for the `jsonbMinus` mutation."""
+input JsonbMinusInput {
+  """
+  An arbitrary string value with no semantic meaning. Will be included in the
+  payload verbatim. May be used to track mutations by the client.
+  """
+  clientMutationId: String
+  minuend: JSON!
+  subtrahend: JSON!
+}
+
+"""The output of our `jsonbMinus` mutation."""
+type JsonbMinusPayload {
+  """
+  The exact same `clientMutationId` that was provided in the mutation input,
+  unchanged and unused. May be used by a client to track mutations.
+  """
+  clientMutationId: String
+  json: JSON
+
+  """
+  Our root query field type. Allows us to run any query from our mutation payload.
+  """
+  query: Query
+}
+
 type KeycloakJwt {
   acr: String
   aud: String
@@ -52297,6 +52323,12 @@ type Mutation {
     """
     input: GenerateQuarterlyReportsInput!
   ): GenerateQuarterlyReportsPayload
+  jsonbMinus(
+    """
+    The exclusive input argument for this mutation. An object type, make sure to see documentation for this object’s fields.
+    """
+    input: JsonbMinusInput!
+  ): JsonbMinusPayload
   stageDirtyFormChanges(
     """
     The exclusive input argument for this mutation. An object type, make sure to see documentation for this object’s fields.
@@ -66928,7 +66960,7 @@ type Query implements Node {
   paymentByRowId(rowId: Int!): Payment
 
   """
-  returns a form_change for a table in the pending state for the current user, i.e. allows to resume the creation of any table row
+  returns list of key-value pairs present in the first argument but not the second argument
   """
   pendingNewFormChangeForTable(tableName: String!): FormChange
 

app/schema/schema.json

@@ -171233,6 +171233,102 @@
           "enumValues": null,
           "possibleTypes": null
         },
+        {
+          "kind": "INPUT_OBJECT",
+          "name": "JsonbMinusInput",
+          "description": "All input for the `jsonbMinus` mutation.",
+          "fields": null,
+          "inputFields": [
+            {
+              "name": "clientMutationId",
+              "description": "An arbitrary string value with no semantic meaning. Will be included in the\npayload verbatim. May be used to track mutations by the client.",
+              "type": {
+                "kind": "SCALAR",
+                "name": "String",
+                "ofType": null
+              },
+              "defaultValue": null
+            },
+            {
+              "name": "minuend",
+              "description": null,
+              "type": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "SCALAR",
+                  "name": "JSON",
+                  "ofType": null
+                }
+              },
+              "defaultValue": null
+            },
+            {
+              "name": "subtrahend",
+              "description": null,
+              "type": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "SCALAR",
+                  "name": "JSON",
+                  "ofType": null
+                }
+              },
+              "defaultValue": null
+            }
+          ],
+          "interfaces": null,
+          "enumValues": null,
+          "possibleTypes": null
+        },
+        {
+          "kind": "OBJECT",
+          "name": "JsonbMinusPayload",
+          "description": "The output of our `jsonbMinus` mutation.",
+          "fields": [
+            {
+              "name": "clientMutationId",
+              "description": "The exact same `clientMutationId` that was provided in the mutation input,\nunchanged and unused. May be used by a client to track mutations.",
+              "args": [],
+              "type": {
+                "kind": "SCALAR",
+                "name": "String",
+                "ofType": null
+              },
+              "isDeprecated": false,
+              "deprecationReason": null
+            },
+            {
+              "name": "json",
+              "description": null,
+              "args": [],
+              "type": {
+                "kind": "SCALAR",
+                "name": "JSON",
+                "ofType": null
+              },
+              "isDeprecated": false,
+              "deprecationReason": null
+            },
+            {
+              "name": "query",
+              "description": "Our root query field type. Allows us to run any query from our mutation payload.",
+              "args": [],
+              "type": {
+                "kind": "OBJECT",
+                "name": "Query",
+                "ofType": null
+              },
+              "isDeprecated": false,
+              "deprecationReason": null
+            }
+          ],
+          "inputFields": null,
+          "interfaces": [],
+          "enumValues": null,
+          "possibleTypes": null
+        },
         {
           "kind": "OBJECT",
           "name": "KeycloakJwt",
@@ -176610,6 +176706,33 @@
               "isDeprecated": false,
               "deprecationReason": null
             },
+            {
+              "name": "jsonbMinus",
+              "description": null,
+              "args": [
+                {
+                  "name": "input",
+                  "description": "The exclusive input argument for this mutation. An object type, make sure to see documentation for this object’s fields.",
+                  "type": {
+                    "kind": "NON_NULL",
+                    "name": null,
+                    "ofType": {
+                      "kind": "INPUT_OBJECT",
+                      "name": "JsonbMinusInput",
+                      "ofType": null
+                    }
+                  },
+                  "defaultValue": null
+                }
+              ],
+              "type": {
+                "kind": "OBJECT",
+                "name": "JsonbMinusPayload",
+                "ofType": null
+              },
+              "isDeprecated": false,
+              "deprecationReason": null
+            },
             {
               "name": "stageDirtyFormChanges",
               "description": null,
@@ -229591,7 +229714,7 @@
             },
             {
               "name": "pendingNewFormChangeForTable",
-              "description": "returns a form_change for a table in the pending state for the current user, i.e. allows to resume the creation of any table row",
+              "description": "returns list of key-value pairs present in the first argument but not the second argument",
               "args": [
                 {
                   "name": "tableName",

docs/concurrentRevisionHandling.md

@@ -0,0 +1,41 @@
+# Handling of Concurrent Revisions
+
+The purpose of this document is to outline how we allow concurrent revisions to be made to a proeject.
+
+## Introduction
+
+By "concurrent revisions" we are referring to the ability for two discrete sets of changes to a project to exist at the same time. In CIF, we limit the number of concurrent revisions on any given project to be two: one "Amendment", and one "General Revision". While this was never intended to be a functionality of CIF, a new user flow was introduced that required it. As such, the approach taken is more of an adaptaion of the existing CIF architecture (which is described in `docs/dbRecordsHistory.md`) than an architecture designed to handle concurrency. The result is that any divergence from the original architecture pre-concureency also appears in the concurrent behaviour. For example, project contacts are handled using a different pattern than the project form in the original architecture, therfore they behave differently from the genral pattern in the concurrent approach as well.
+
+### Terminology
+
+There are three terms we need to use to identify the three `form_change` records in question: "committing", "pending", and "original parent". I'll use the more common scenario to outline the terminology used throughout this document.
+An Amendment is opened on a project, and left open while it is being negotiated. While it is open, a General Revision is opened on that same project, a small change is made, and the revision is committed. The point in time of the General Revision being committed is where the terminology gets its roots. In this example, the General Revision is **committing**, the still-open amendment is **pending**, and the parent revision of the Amendment is the **original parent**.
+
+## Approach
+
+A solution that would allow us to handle concurrency without user input on conflict resolution was needed. To achieve this, the approach taken is comparable to a git rebase. When committing and pending are in conflict, the changes made in pending are applied on top of the committing form change, as if the committing `form_change` were the original parent of the pending `form_change`. While users commit on a `project_revision` level, the change propogates down to the `form_change` level, so when we're talking about this here it is at the `form_change` granularity, and the heart it takes place in the function `cif.commit_form_change_internal`.
+
+One of the ways our various forms can be categorized would be:
+
+- forms a project can have at most one of (`funding_parameter_EP`, `funding_parameter_IA`, `emission_intensity`, `project_summary_report`)
+- 'project_contact' are either primary or secondary, and have a `contactIndex`
+- 'project_manager' are categorized by `projectManagerLabelId`
+- 'reporting_requirement' have a `reportingRequirementIndex` based on the `json_schema_name`
+
+Form changes can have an operation of `create`, `update`, or `archive`, each of which need to be handled for all of the above categories. This results in several unique cases, which have been explained case-by-case using in-line in the `commit_form_change_internal` where they have more context.
+
+After each of the following cases, the `previous_form_change_id` of the pending `form_change` is set to be the id of the committing `form_change`, which leaves every form change with a `previous_form_change_id` of the **last commit** corresponding `form_change`, while preserving the option of a full history by maintaining accurate `created_at`, `updated_at`, and `archived_at` values for all `form_change`.
+
+### Create (the general approach)
+
+If the committing project revision creates a form change that does not exist in the pending revision, for example adding a milestone, then the form needs to be created in the pending revision. In cases such as contacts which have a `contactIndex` associated with them, the index needs to be determined by the existing indices in the pending revision. This will allow the indices to stay sequential if other items were added or removed in the pending revision.
+
+### Update
+
+1. If the committing form change contains the same data as the pending's original parent, then no change to the pending data is needed.
+2. If the committing and pending form changes both have changes from the pending form change's parent, then set the pending form change's new_form_data to be the committing form change's, plus the changes made in the penging form change. The result is what would the data would have been if the pending form change had the committing as it's parent, similar to a git rebase.
+3. If the pending form change hasn't made any changes since its creation, but the committing form change has, set the pending form change's new_form_data to be the committing form change's, as it is the latest information.
+
+### Archive (the general approach)
+
+If the committing `form_change` is being archived, the pending form change can simply be deleted as it never would have been created in the first place had the committing project revision been the original parent of the pending revision.

schema/deploy/functions/jsonb_minus.sql

@@ -0,0 +1,31 @@
+-- Deploy cif:functions/jsonb_minus to pg
+
+begin;
+-- A note on the functionality:
+-- If a key is present in the subtrahend but not the minuend, it will not appear in the result set.
+-- {"a": 1, "b": 3} - {"a": 1, "b": 2, "c": 3} =  {"b": 3}
+-- If however a key is present in the minuend but not the subtrahend, it will appear in the result set with its value.
+-- {"a": 1, "b": 3, "c": 3} - {"a": 1, "b": 2} =  {"b": 3, "c": 3}
+
+-- This behaviour fits our needs at the time of writing this, so the additional complexity of handling the other cases is not needed.
+
+
+create or replace function cif.jsonb_minus(minuend jsonb, subtrahend jsonb)
+  returns jsonb as
+$$
+declare
+  difference jsonb;
+begin
+    select jsonb_object_agg(key, value) into strict difference
+    from (
+        select * from jsonb_each($1)
+        except select * from jsonb_each($2)
+    ) as temp;
+
+    return difference;
+end
+$$ language plpgsql volatile;
+
+comment on function cif.pending_new_form_change_for_table(text) is
+  'returns list of key-value pairs present in the first argument but not the second argument';
+commit;

schema/deploy/mutations/commit_form_change.sql

@@ -12,7 +12,13 @@ begin
     validation_errors = coalesce(form_change_patch.validation_errors, validation_errors)
   where id=row_id;
 
-  return (select cif_private.commit_form_change_internal((select row(form_change.*)::cif.form_change from cif.form_change where id = row_id)));
+  return (select cif_private.commit_form_change_internal(
+    (select row(form_change.*)::cif.form_change from cif.form_change where id = row_id),
+    -- This is guaranteed to be a single row as we have unique inidices on pending general revision and pending amendment
+    (select id  from cif.project_revision
+      where project_id=(select project_id from cif.project_revision where id = form_change_patch.project_revision_id)
+      and change_status = 'pending' and id != form_change_patch.project_revision_id)
+  ));
 end;
   $$ language plpgsql volatile;
 

schema/deploy/mutations/commit_form_change@1.15.0.sql

@@ -0,0 +1,23 @@
+-- Deploy cif:mutations/commit_form_change to pg
+-- requires: tables/form_change
+
+begin;
+
+create or replace function cif.commit_form_change(row_id int, form_change_patch cif.form_change)
+    returns cif.form_change as $$
+begin
+
+  update cif.form_change set
+    new_form_data = coalesce(form_change_patch.new_form_data, new_form_data),
+    validation_errors = coalesce(form_change_patch.validation_errors, validation_errors)
+  where id=row_id;
+
+  return (select cif_private.commit_form_change_internal((select row(form_change.*)::cif.form_change from cif.form_change where id = row_id)));
+end;
+  $$ language plpgsql volatile;
+
+grant execute on function cif.commit_form_change to cif_internal, cif_external, cif_admin;
+
+comment on function cif.commit_form_change is 'Custom mutation to commit a form_change record via the API. Only used for records that are independent of a project such as the lists of contacts and operators.';
+
+commit;