Skip to content

Correct domain-fact errors in the overdue inbound shipments contract - #2

Open
matthewguerra-cog wants to merge 4 commits into
spec-demo-basefrom
devin/1787182177-shipment-exceptions-spec-fixups
Open

matthewguerra-cog wants to merge 4 commits into
spec-demo-basefrom
devin/1787182177-shipment-exceptions-spec-fixups

Conversation

@matthewguerra-cog

@matthewguerra-cog matthewguerra-cog commented Aug 19, 2026 •

Copy link
Copy Markdown
Collaborator

✨ Description of Change

Link to GitHub issue or Jira ticket: follow-up to #1 (spec-driven development rehearsal, Act 1)

Description:

Accuracy-only follow-up to the contract merged in #1, now rebased on top of the merged Act 2 work (#3). No agreed behavior changes — calendar-day daysLate, inbound-includes-child-locations, the derived status enum, default max 50 and the no-warehouse 400 all stay exactly as approved. What changes is where the contract misstated the domain model.

  • name was declared nullable: true with the comment "(nullable in the domain)". It isn't: Shipment.groovy:169 declares name(nullable: false, blank: false, maxSize: 255). Now non-nullable and in required.
  • expectedShippingDate was documented as "required in the domain, so always present" but was missing from required while expectedDeliveryDate was in it. Added, so the two agree.
  • shipmentItemCount stays a plain non-nullable integer, now with a description that explains why: it is a Hibernate formula field constrained nullable: true (Shipment.groovy:160,206), but the merged ShipmentExceptionService emits shipment.shipmentItemCount ?: shipment.shipmentItems?.size() ?: 0, so the response value is always present. (An earlier revision of this PR marked it nullable: true off the domain constraint alone; that would have documented a response shape the implementation never produces.)
  • shipmentItemCount is also added to required, so the schema matches that always-present prose.
  • shipmentNumber keeps required/non-nullable, with a note that the domain column is nullable: true but ShipmentService.saveShipment populates it via shipmentIdentifierService.generate (ShipmentService.groovy:508) — so required here is an endpoint guarantee, not a domain-level one.
  • Criterion 1 said a row "appears in data, keyed by its shipmentNumber" — data is an array, so it now says "identified by matching shipmentNumber".
  • The PATH CHOICE paragraph had a garbled clause ("declared ahead of any new mapping would matter"); rewritten. The mapping analysis itself is unchanged and still holds.
  • Criteria 5/10 and the operation description now note that the ?: actualDeliveryDate tail of dateDelivered() resolves a transient whose getter derives from the RECEIVED event (static transients, Shipment.groovy:108; getActualDeliveryDate(), :400-403) — so RECEIVED/DELIVERED events are the only exclusion signals and nobody seeds a fixture against a non-existent column. This corrects a review comment that claimed a standalone actualDeliveryDate column could exclude a shipment.
  • The NOTE ON INTENT block still said the endpoint "does not exist yet" and that the controller and URL mapping were "proposed, not present". Both landed with Overdue inbound shipments: endpoint, contract tests, and inbound list Overdue view (spec-driven Act 2) #3 (ShipmentExceptionApiController.groovy, UrlMappings.groovy:1262), so it now says the spec was authored contract-first and has since been implemented there.

This PR's diff touches only openapi/specs/shipment-exceptions-api.yaml and openapi/specs/shipment-exceptions-acceptance-criteria.md — no controller, URL mapping, React or contract-test changes here (the implementation itself already merged in #3).

Consistency with the merged implementation

Rebasing onto the merged Act 2 work also resolved a conflict in the criteria doc, where Act 2 converted the "Open questions" section into "Decisions": this PR keeps that Decisions wording and only updates the stale cross-reference in criterion 10. Every required/nullable claim in the spec was cross-checked against ShipmentExceptionService.getOverdueInboundShipments, ShipmentExceptionApiController and characterization/contract/test_shipment_exceptions_api_contract.py; no further mismatch remains.

Verification

npx @redocly/cli@1.34.2 lint --config openapi/redocly.yaml 'openapi/specs/*.yaml' openapi/components/common.yaml — 0 errors, 0 warnings (the exact command the openapi-lint CI job runs).

Open items

The naming/layout suggestions from review on #1 — renaming to shipment-exception-api.yaml and moving prescriptive specs to e.g. openapi/proposals/ — are deliberately not done here; the paths were specified as-is and are yours to decide.

Devin-Org: engineering

Link to Devin session: https://app.devin.ai/sessions/fac0eacd88a44c08b704f4eca4926851
Requested by: @matthewguerra-cog


Devin Review

Status Commit
🟢 Reviewed 6a76d42
Open in Devin Review (Staging)

@matthewguerra-cog matthewguerra-cog self-assigned this Aug 19, 2026
@devin-ai-integration

Copy link
Copy Markdown

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment, CI, and merge conflict monitoring

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Open in Devin Review

staging-devin-ai-integration[bot]

This comment was marked as resolved.

Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
@devin-ai-integration
devin-ai-integration Bot force-pushed the devin/1787182177-shipment-exceptions-spec-fixups branch from 7c39723 to 185d970 Compare August 20, 2026 01:22

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 3 new potential issues.

Open in Devin Review

Comment on lines +201 to +204
- name
- origin
- destination
- expectedShippingDate

@devin-ai-integration devin-ai-integration Bot Aug 20, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: shipmentNumber requiredness is an endpoint guarantee that legacy rows can break

The new note explains required for shipmentNumber from ShipmentService.saveShipment generating one. The service simply passes through shipment.shipmentNumber (grails-app/services/org/pih/warehouse/shipping/ShipmentExceptionService.groovy:62) and the domain column is nullable: true (grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy:167), so any shipment created through another path (imports, data migration, direct SQL) would yield a null value for a field the contract declares required. Same class of risk applies to status, which is emitted as shipment.status?.code?.name() and declared required with a closed enum.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch on the constraint — shipmentNumber(nullable: true, ...) (Shipment.groovy:171) is indeed looser than the contract.

Keeping it required and non-nullable, because for this endpoint the response value is always populated: ShipmentService.saveShipment assigns shipment.shipmentNumber = shipmentIdentifierService.generate(shipment) (:508) on every shipment created through the service, and the merged ShipmentExceptionService passes it straight through. The domain column is nullable only to accommodate direct saves that bypass that path, which is not a shape a warehouse manager's overdue list should be written against.

I am adding a one-line note to the field description recording that the column is nullable but populated by shipmentIdentifierService, so nobody later reads required as a domain-level guarantee. Flagging for @matthewguerra-cog: if you'd rather the contract mirror the raw domain constraint here, say so and I'll loosen it.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed on the mechanism — that's exactly why the note calls it an endpoint guarantee rather than a domain one, and I'm leaving shipmentNumber required: a null shipment number on an overdue-shipment row is unactionable for the warehouse manager (there is nothing to chase the carrier with), so a legacy row like that is a data problem to surface, not a response shape to bless. @matthewguerra-cog can overrule me if he'd rather the contract mirror the raw column.

On status: that one isn't the same risk. Shipment.getStatus() has no null path — every branch returns a ShipmentStatus with a non-null code, with PENDING as the unconditional else — so no creation path can produce a null status. Detail in the other thread.

Comment on lines +32 to +35
event (`dateDelivered()` non-null; its `actualDeliveryDate` fallback is
transient and derives from the `RECEIVED` event, so `RECEIVED`/`DELIVERED`
events are the only signals) does not appear, even when its derived status
is `PARTIALLY_RECEIVED`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: dateDelivered()/actualDeliveryDate claim verified against the domain

Checked the corrected claim: dateDelivered() resolves the RECEIVED event, falls back to DELIVERED, then to actualDeliveryDate (grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy:677-683), and actualDeliveryDate is a transient (:108) whose getter returns the RECEIVED event date (:400-403). So the new wording — RECEIVED/DELIVERED events being the only exclusion signals, with no standalone column to seed — matches the domain, and the fallback is indeed redundant.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed, thanks — that matches the line references this change is built on, no action needed.

staging-devin-ai-integration[bot]

This comment was marked as resolved.

Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 1 new potential issue.

Open in Devin Review

Comment on lines +201 to +204
- name
- origin
- destination
- expectedShippingDate

@devin-ai-integration devin-ai-integration Bot Aug 20, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔍 status is required and enum-constrained but derived from a nullable getter

Unchanged by this PR, but relevant to its stated goal of aligning required/nullable claims with the implementation: the service emits status: shipment.status?.code?.name(), which can be null if getStatus() returns null, yet status remains in required with a closed enum. Since this PR audited the other required fields, this one may deserve the same treatment (either document the guarantee or make the field nullable).

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checked this one and it doesn't hold: Shipment.getStatus() cannot return null. Every branch returns a freshly constructed ShipmentStatus with a non-null code — RECEIVED / PARTIALLY_RECEIVED / SHIPPED, and PENDING as the unconditional else. So shipment.status?.code?.name() always yields one of the enum names, and status stays required with the closed enum.

The enum in the contract deliberately omits CREATED for the same reason: the derived status never produces it.

Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>

@staging-devin-ai-integration staging-devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 1 new potential issue.

Open in Devin Review (Staging)
Debug

Playground

- expectedDeliveryDate
- daysLate
- status
- shipmentItemCount

@staging-devin-ai-integration staging-devin-ai-integration Bot Aug 20, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔍 status is in required but the implementation can emit null

The status property stays in the required list with a closed enum, yet the implementation emits shipment.status?.code?.name() (grails-app/services/org/pih/warehouse/shipping/ShipmentExceptionService.groovy:69), which is null-safe navigated. Shipment.getStatus() (grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy:437) is generally expected to return a non-null status, but since this PR audits required/nullable claims against the implementation, it may be worth confirming that no reachable code path yields a null status for a shipment that passes the overdue/unreceived filters — otherwise the contract would declare a required, non-nullable enum for a value that can serialize as null.

Open in Devin Review (Staging)

Was this helpful? React with 👍 or 👎 to provide feedback.

Debug

Playground

devin-ai-integration[bot]

This comment was marked as resolved.

Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 1 new potential issue.

Open in Devin Review

Comment on lines 59 to +61
either event excludes a shipment even when its derived status is
PARTIALLY_RECEIVED.
PARTIALLY_RECEIVED (actualDeliveryDate is transient and derives from
the RECEIVED event, so RECEIVED/DELIVERED events are the only signals).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: Claims about the merged implementation cross-check out

Verified the accuracy corrections against the merged code: the endpoint and mapping do exist (grails-app/controllers/org/pih/warehouse/UrlMappings.groovy:1262, ShipmentExceptionApiController), dateDelivered()'s ?: actualDeliveryDate tail resolves the transient getter that reads the RECEIVED event (Shipment.groovy:400-403, :677-683), so RECEIVED/DELIVERED events really are the only exclusion signals; name(nullable: false) and expectedShippingDate(nullable: false) match the new required entries; and shipmentItemCount is always populated via the ?: size() ?: 0 fallback in the service. The status enum excluding RECEIVED also holds, since getStatus() only returns RECEIVED when a RECEIVED event exists, which already forces exclusion.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Matches my own cross-check — nothing to change here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant