docs: ADRs for the PM-KISAN grievance and application status [#60]

.gitignore

@@ -178,7 +178,8 @@ test_request.json
 
 # catalogPublish handler's local output root (config/local-beckn-one-bap.yaml)
 /catalog/
-/docs/
+/docs/*
+!/docs/adr/
 /dev_docs/
 
 # Deployment configs carry real key material and must never be committed.

config/mappings/pmfby/grievance.status.yaml

@@ -0,0 +1,117 @@
+# PMFBY status -> POST /krphapi/FGMS/GetGrievenceTicketsStatus.
+# Reads a grievance back by ticket number and phone. Only listed fields are
+# returned; the farmer's personal details are dropped.
+# Required fields and formats are checked by the Grievance pack.
+
+request: |
+  (
+    $attributes := beckn.message.contract.commitments[0].commitmentAttributes;
+    {
+      "requestorMobileNo": $attributes.applicantMobile,
+      "GrievenceSupportTicketNo": $attributes.case.ticketNo
+    }
+  )
+
+# Empty PMFBY fields are dropped. No record, or one for another ticket, is a
+# 400 in our words; any other failure is a 502. PMFBY's message is logged,
+# never returned.
+response: |
+  (
+    /* Constants */
+    $PMFBY_SUCCESS_CODE := "1";
+    $SCHEME := { "code": "PMFBY", "name": "Pradhan Mantri Fasal Bima Yojana" };
+    $INFORMATION_MODE := "Direct";
+    $COMMITMENT_STATUS_ACTIVE := "ACTIVE";
+    $DEFAULT_CASE_STATUS := "UnderReview";
+    $CASE_STATUS_CODES := { "open": "Registered", "resolved": "Resolved" };
+    $SEASON_NAMES := { "1": "Kharif", "2": "Rabi", "3": "Zaid" };
+    $TIMESTAMP_FORMAT := "[Y0001]-[M01]-[D01]T[H01]:[m01]:[s01]Z";
+
+    /* e.g. "2026-10-12T11:02:49.000Z" */
+    $RFC3339_PATTERN := /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})$/;
+    $DIGITS_PATTERN := /^[0-9]+$/;
+    $YEAR_PATTERN := /^[0-9]{4}$/;
+
+    $MSG_NOT_FOUND := "No grievance was found for this ticket number and phone number.";
+    $MSG_UNAVAILABLE := "PMFBY could not return the grievance status right now. Please try again later.";
+
+    $ERROR_REFUSED := { "status": 400, "code": "BIZ_GENERIC_ERROR" };
+    $ERROR_UNAVAILABLE := { "status": 502, "code": "NET_DOWNSTREAM_UNAVAILABLE" };
+    /* PMFBY fails everything with responseCode "0", so its wording (lower case)
+       is the only way to tell a caller mistake from a PMFBY fault. */
+    $KNOWN_REFUSALS := { "no record found": $MSG_NOT_FOUND };
+
+    /* Helpers */
+    /* PMFBY sends null or "" for missing values. */
+    $isText := function($value) { $type($value) = "string" and $value != "" };
+    $asText := function($value) { $isText($value) ? $value };
+    /* Ids come as numbers or digit strings, and 0 means none. */
+    $asId := function($value) {
+      ($type($value) = "number" or $type($value) = "string")
+        and $contains($string($value), $DIGITS_PATTERN) and $number($string($value)) != 0
+        ? $string($value)
+    };
+    /* Drops an object with no fields instead of sending {}. */
+    $omitIfEmpty := function($object) { $exists($keys($object)[0]) ? $object };
+    $error := function($kind, $message, $cause) {
+      { "_error": $merge([$kind, { "message": $message, "cause": $cause }]) }
+    };
+
+    /* Inputs */
+    $commitment := beckn.message.contract.commitments[0];
+    $attributes := $commitment.commitmentAttributes;
+    /* [0] reads a bare record or a list of one alike. */
+    $record := response.responseDynamic[0];
+    $pmfbyMessage := $type(response.responseMessage) = "string" ? $trim(response.responseMessage);
+    $refusalMessage := $pmfbyMessage ? $lookup($KNOWN_REFUSALS, $lowercase($pmfbyMessage));
+    $isAccepted := $string(response.responseCode) = $PMFBY_SUCCESS_CODE;
+    /* PMFBY reads by phone alone, so a record for another ticket is no record. */
+    $isOtherTicket := $exists($record.GrievenceSupportTicketNo)
+      and $string($record.GrievenceSupportTicketNo) != $string($attributes.case.ticketNo);
+    $isFound := $isAccepted and ($isText($record.ApplicationNo) or $isText($record.TicketStatus)) and $not($isOtherTicket);
+    $mappedStatus := $isText($record.TicketStatus) ? $lookup($CASE_STATUS_CODES, $lowercase($trim($record.TicketStatus)));
+    $caseStatus := $exists($mappedStatus) ? $mappedStatus : $DEFAULT_CASE_STATUS;
+    $requestYear := $asId($record.RequestYear);
+    $cropYear := $requestYear and $contains($requestYear, $YEAR_PATTERN) ? $requestYear;
+    $filedOn := $isText($record.InsertDateTime) and $contains($record.InsertDateTime, $RFC3339_PATTERN)
+      ? $fromMillis($toMillis($record.InsertDateTime), $TIMESTAMP_FORMAT);
+    /* The officer's answer; "" until there is one. */
+    $reply := $asText($isText($record.latestRemark) ? $trim($record.latestRemark));
+
+    /* Output */
+    $isFound
+    ? {
+      "context": $merge([beckn.context, { "action": "on_status", "timestamp": $now() }]),
+      "message": {
+        "contract": $merge([beckn.message.contract, {
+          "commitments": [$merge([$commitment, {
+            "status": { "descriptor": { "code": $COMMITMENT_STATUS_ACTIVE } },
+            "commitmentAttributes": {
+              "@context": $attributes.`@context`,
+              "@type": $attributes.`@type`,
+              "informationMode": $INFORMATION_MODE,
+              "scheme": $SCHEME,
+              "enrolmentId": $asText($record.ApplicationNo),
+              "cropYear": $cropYear,
+              "season": $lookup($SEASON_NAMES, $asId($record.RequestSeason)),
+              "grievance": {
+                "category": $omitIfEmpty({ "code": $asId($record.TicketCategoryID), "name": $asText($record.TicketCategoryName) }),
+                "subCategory": $omitIfEmpty({ "code": $asId($record.TicketSubCategoryID), "name": $asText($record.TicketSubCategoryName) }),
+                "description": $asText($record.GrievenceDescription)
+              },
+              "case": {
+                "ticketNo": $attributes.case.ticketNo,
+                "status": { "code": $caseStatus },
+                "filedOn": $filedOn,
+                "reply": $reply,
+                "cropName": $asText($record.CropName)
+              }
+            }
+          }])]
+        }])
+      }
+    }
+    : $isAccepted ? $error($ERROR_REFUSED, $MSG_NOT_FOUND)
+    : $exists($refusalMessage) ? $error($ERROR_REFUSED, $refusalMessage, $pmfbyMessage)
+    : $error($ERROR_UNAVAILABLE, $MSG_UNAVAILABLE, $pmfbyMessage)
+  )

config/mappings/pmfby/grievance.support.yaml

@@ -0,0 +1,112 @@
+# PMFBY support -> POST /krphapi/FGMS/AddKRPHNCIPGrievenceSupportTicket.
+# Files a grievance; no OTP. "Grievence" is PMFBY's spelling.
+# Required fields and formats are checked by the Grievance pack.
+# The two halves cannot share variables, so the default codes are in both.
+
+request: |
+  (
+    /* Constants */
+    $DEFAULT_CATEGORY_CODE := "3";
+    $DEFAULT_SUB_CATEGORY_CODE := "10";
+    $DEFAULT_RECEIPT_SOURCE_ID := "134306";
+    $SEASON_CODES := { "Kharif": "1", "Rabi": "2", "Zaid": "3" };
+
+    $DATE_FORMAT := "[Y0001]-[M01]-[D01]";
+    $IST_OFFSET := "+0530";
+
+    /* Helpers */
+    $orDefault := function($value, $default) { $exists($value) ? $string($value) : $default };
+
+    /* Inputs */
+    $channel := beckn.message.support.channels[0];
+    $grievance := $channel.grievance;
+    $filedAt := $exists($channel.complaintDate) ? $toMillis($channel.complaintDate) : $millis();
+
+    /* Output */
+    {
+      "requestorMobileNo": $channel.applicantMobile,
+      "applicationNo": $channel.enrolmentId,
+      "requestYear": $string($channel.cropYear),
+      "requestSeason": $lookup($SEASON_CODES, $channel.season),
+      "ticketCategoryID": $orDefault($grievance.category.code, $DEFAULT_CATEGORY_CODE),
+      "ticketSubCategoryID": $orDefault($grievance.subCategory.code, $DEFAULT_SUB_CATEGORY_CODE),
+      "grievenceDescription": $trim($grievance.description),
+      "complaintDate": $fromMillis($filedAt, $DATE_FORMAT, $IST_OFFSET),
+      "receiptSourceID": $orDefault($channel.receiptSourceId, $DEFAULT_RECEIPT_SOURCE_ID)
+    }
+  )
+
+# Echoes the request and adds the ticket. A known PMFBY refusal is a 400 in our
+# words; any other failure is a 502. PMFBY's message is logged, never returned.
+response: |
+  (
+    /* Constants */
+    $DEFAULT_CATEGORY_CODE := "3";
+    $DEFAULT_SUB_CATEGORY_CODE := "10";
+    $PMFBY_SUCCESS_CODE := "1";
+    $PROVIDER_NAME := "PMFBY Grievance Portal";
+    $SCHEME := { "code": "PMFBY", "name": "Pradhan Mantri Fasal Bima Yojana" };
+    $INFORMATION_MODE := "Direct";
+    $CASE_STATUS_REGISTERED := "Registered";
+    $TIMESTAMP_FORMAT := "[Y0001]-[M01]-[D01]T[H01]:[m01]:[s01]Z";
+
+    $MSG_PHONE_MISMATCH := "The phone number does not match the one registered for this application number.";
+    $MSG_APPLICATION_NOT_FOUND := "No PMFBY application was found for this application number.";
+    $MSG_UNAVAILABLE := "PMFBY could not register the grievance right now. Please try again later.";
+
+    $ERROR_REFUSED := { "status": 400, "code": "BIZ_GENERIC_ERROR" };
+    $ERROR_UNAVAILABLE := { "status": 502, "code": "NET_DOWNSTREAM_UNAVAILABLE" };
+    /* PMFBY fails everything with responseCode "0", so its wording (lower case)
+       is the only way to tell a caller mistake from a PMFBY fault. */
+    $KNOWN_REFUSALS := {
+      "mobile number not matched": $MSG_PHONE_MISMATCH,
+      "application details not exists": $MSG_APPLICATION_NOT_FOUND
+    };
+
+    /* Helpers */
+    $orDefault := function($value, $default) { $exists($value) ? $string($value) : $default };
+    $error := function($kind, $message, $cause) {
+      { "_error": $merge([$kind, { "message": $message, "cause": $cause }]) }
+    };
+
+    /* Inputs */
+    $channel := beckn.message.support.channels[0];
+    $grievance := $channel.grievance;
+    $ticketNo := response.responseDynamic.GrievenceSupportTicketNo;
+    $pmfbyMessage := $type(response.responseMessage) = "string" ? $trim(response.responseMessage);
+    $refusalMessage := $pmfbyMessage ? $lookup($KNOWN_REFUSALS, $lowercase($pmfbyMessage));
+    $hasTicket := $type($ticketNo) = "number" or ($type($ticketNo) = "string" and $ticketNo != "");
+    /* "Ticket Already Raised" also comes back as success with a ticket. */
+    $isLodged := $string(response.responseCode) = $PMFBY_SUCCESS_CODE and $hasTicket;
+
+    /* Output */
+    $isLodged
+    ? {
+      "context": $merge([beckn.context, { "action": "on_support", "timestamp": $now() }]),
+      "message": {
+        "support": {
+          "channels": [{
+            "@context": $channel.`@context`,
+            "@type": $channel.`@type`,
+            "informationMode": $INFORMATION_MODE,
+            "provider": { "id": $channel.provider.id, "descriptor": { "name": $PROVIDER_NAME } },
+            "scheme": $SCHEME,
+            "enrolmentId": $channel.enrolmentId,
+            "grievance": {
+              "category": { "code": $orDefault($grievance.category.code, $DEFAULT_CATEGORY_CODE) },
+              "subCategory": { "code": $orDefault($grievance.subCategory.code, $DEFAULT_SUB_CATEGORY_CODE) },
+              "description": $trim($grievance.description)
+            },
+            "case": {
+              "ticketNo": $string($ticketNo),
+              "status": { "code": $CASE_STATUS_REGISTERED },
+              /* Lodge time, so it agrees with what a status read reports. */
+              "filedOn": $fromMillis($millis(), $TIMESTAMP_FORMAT)
+            }
+          }]
+        }
+      }
+    }
+    : $exists($refusalMessage) ? $error($ERROR_REFUSED, $refusalMessage, $pmfbyMessage)
+    : $error($ERROR_UNAVAILABLE, $MSG_UNAVAILABLE, $pmfbyMessage)
+  )

config/provider-adapter.yaml

@@ -505,6 +505,32 @@ modules:
               # concurrency for this capability.
               searchConcurrency: 1
 
+          # ------------------------------------------------------------------
+          # Grievance -- support files a grievance, status reads it back.
+          # ------------------------------------------------------------------
+          - id: Grievance
+            config:
+              bindingKeys: "pmfby|openagrinet:Grievance"
+
+              # Paired by position, tried in order: status names the binding on
+              # its contract, support on its channel.
+              providerIdAt: "message.contract.commitments[].offer.provider.id, message.support.channels[].provider.id"
+              capabilityCodeAt: "message.contract.commitments[].commitmentAttributes.@type, message.support.channels[].@type"
+
+              # Logs in at PMFBY's NICUsersLogin and sends the token bare in
+              # Authorization, held until the login reply's validTo.
+              # tokenUrl is set per deployment.
+              pmfby:
+                authScheme: tokenHeader
+                tokenUrl: <>
+                tokenUserField: appAccessUID
+                tokenUserEnv: PMFBY_ACCESS_UID
+                tokenSecretField: appAccessPWD
+                tokenSecretEnv: PMFBY_ACCESS_PWD
+                tokenResponseField: responseDynamic.token.Token
+                tokenExpiryField: responseDynamic.token.validTo
+                headerName: Authorization
+
       # Declaring a step above is not enough: THIS list is what runs. A step
       # that appears under providerSteps but not here never executes, and the
       # request falls through to the 404 above -- which looks like a registry
@@ -516,6 +542,7 @@ modules:
         - MandiPrice          # its binding key, or pass through
         - KnowledgeAdvisory   # its binding key, or pass through
         - AgricultureFacility # its binding key, or pass through
+        - Grievance           # its binding key, or pass through
         - signAck          # signs whatever the step answered with
 
 # ----------------------------------------------------------------------------

docs/adr/0000-template.md

@@ -0,0 +1,23 @@
+# ADR-0000 — Title
+
+**Status:** Proposed | Accepted | Superseded by ADR-NNNN
+**Date:** YYYY-MM-DD
+
+## Context
+
+What forced a decision. The constraint, not the preamble.
+
+## Decision
+
+What was chosen, stated so that a reader can tell whether a given change
+complies with it.
+
+## Alternatives considered
+
+What was rejected, and the specific property that disqualified it. "It was
+worse" is not a reason; "it resolves columns by reflection at runtime" is.
+
+## Consequences
+
+What this costs, including the cases it makes harder. An ADR that lists only
+benefits is advocacy, not a record.

docs/adr/0001-provider-envelopes-in-common.md

@@ -0,0 +1,47 @@
+# ADR-0001 — Provider envelopes live in common, with capability hooks
+
+**Status:** Accepted
+**Date:** 2026-10-23
+
+## Context
+
+PM-KISAN does not take plain JSON. Its grievance service takes AES-GCM under a
+fixed key and nonce with a service token inside the body; its chatbot (OTP)
+service takes AES-128-CBC with a fresh key sent beside the ciphertext. Some
+calls must first verify an OTP the farmer received. Mappings are published
+files and must stay plain JSON, and must never carry the token.
+
+## Decision
+
+`internal/common/envelope` seals a mapped request and opens the answer:
+`aesGcm` (fixed key and nonce, from env vars named in config) and
+`aesCbcKeyInBand` (fresh key per request, `cipher@key`). It adds the service
+token after the mapping runs. It can verify a challenge on the provider before
+the guarded call (`otpVerifyPath`, `otpVerifyActions`), on its own time budget
+(`otpVerifyTimeoutMs`). Its HTTP client refuses an off-host redirect, as
+common's does.
+
+What only a capability knows comes in as `envelope.Hooks`: where its payload
+carries the challenge, and what its provider's "yes" looks like. Settings are a
+provider block in the step's config, read by `envelope.Parse`; `envelope:` is
+required whenever any `envelope*` setting is present, so a typo cannot send
+plaintext.
+
+## Alternatives considered
+
+- **Inside the Grievance plugin.** The next provider with an encrypted
+  upstream would have to import a package named for another capability or copy
+  it.
+- **The `encrypter`/`decrypter` plugins.** They do X25519 key agreement for
+  Beckn payloads; PM-KISAN's fixed-key GCM and key-in-band CBC are neither.
+- **Encryption in the mapping.** JSONata has no crypto, and the token would
+  have to be in a public file.
+
+## Consequences
+
+The GCM nonce is fixed because PM-KISAN requires it. With one key and one
+nonce, two ciphertexts give the XOR of their plaintexts and a ciphertext can
+be forged; this envelope adds no confidentiality or integrity of its own and
+TLS is the only protection. A nonce shorter than 12 bytes is refused. The CBC
+key travels with the ciphertext, so that envelope is obfuscation; its token is
+the only secret.

docs/adr/0002-an-action-served-by-another-participant.md

@@ -0,0 +1,32 @@
+# ADR-0002 — An action served by another participant is named by its binding key
+
+**Status:** Accepted
+**Date:** 2026-10-23
+
+## Context
+
+PM-KISAN grievance's `init` (send the OTP) and the OTP verify before `support`
+and `status` are served by the chatbot service, not the grievance service. A
+binding has one participant, so one `baseUrl`. The chatbot service is already
+a participant in the registry for application status.
+
+## Decision
+
+The provider block names the OTP service by binding key:
+`otpBindingKey: "pmkisan-chatbot|openagrinet:SchemeApplication"`.
+`common.Config.HostedElsewhere` (provider → action → binding key) sends those
+actions to that participant's `baseUrl`, read from the registry per call with
+the same active checks as any participant (`common.HostOf`). The verify reads
+it the same way. An unpublished binding is a 502.
+
+## Alternatives considered
+
+- **An env var with the host** (`otpBaseUrlEnv`). The address lived in two
+  places, and the env one skipped the registry's status checks.
+- **A `Router` interface on the envelope.** It existed only for this redirect
+  and hid routing inside an encryption concern.
+
+## Consequences
+
+Grievance depends on the chatbot's binding being active in the registry. Moving
+the OTP service is one registry write, with no restart.