Merged architecture and verification record

Owner-scoped shipments, shipped from file to live context

PR #64 merged a D1-backed shipments platform at /shipments, deterministic and AI-assisted import, scheduled SafeCube enrichment, and LOCODE-linked risk context.

#64Merged

Squash f26c517d

A private operations surface

Every shipment query is scoped by the signed-in owner. Browser cache keys also include that identity, and responses carrying shipment data use private, no-store caching.

Storage

Cloudflare D1

Shipments, import previews, enrichments, events, and owner-aware uniqueness live in a relational schema.

Workspace

/shipments

Search, sort, expand, add, import, stop, restart, and delete from one responsive table and card surface.

Enrichment

SafeCube every 30 minutes

A bounded scheduled job advances active tracking and stores route, vessel, status, and event context.

Risk context

LOCODE joins

Current and downstream ports link shipment movement to the dashboard's news and forecast sources.

Four connected lanes

Hover any node to trace its lane. Solid arrows show request and data flow. Scheduled work is called out in amber.

Interactive request path
Browser
Shipments UIAdd, import, inspect, and control tracking.
Worker
Owner-authenticated APIRoutes under /api/shipments.
Boundary
Validate and scopeTyped drafts plus owner email predicates.
Persistence
D1 storeRows, previews, enrichment, and events.
Response
Private UI stateOwner-keyed cache, private and no-store.
CSV and XLSX import path
Upload
CSV / XLSX / XLSMFile goes to the server untouched.
First pass
Deterministic parserKnown aliases and CargoWise layouts.
Fallback
LLM normalizationOnly unrecognized rows take this path.
Review
D1 previewOwner-bound, expiring, single-consume payload.
Confirm
Insert selected rowsConflicts are reported, not duplicated.
Scheduled enrichment path
Timer
30-minute cronClaims a bounded active batch.
Provider
SafeCubeRoute, AIS, vessel, status, and events.
Adapter
Captured schemaNarrow nullable variants from live payloads.
Mutation
Race-safe D1 writeTracking state and enriched context advance.
Policy
Next poll or stopBackoff, delivery, and error transitions.
Risk context path
Shipment
Current routeOrigin, current, and downstream ports.
Join key
Normalize LOCODEPorts resolve through one stable code.
Sources
News and forecastsExisting dashboard data sources are reused.
Context API
Numeric vessel IDs keptIMO and MMSI normalize at the parse boundary.
Expanded row
Decision contextTimeline, vessel, port news, and outlook.
request and datascheduled provider work

What changed, and why

The PR replaces a single legacy shipment detail route with a complete owner-scoped lifecycle, without removing the existing shipment notification behavior.

Foundation

D1 ownership and lifecycle

  • Strict owner predicates govern list, read, update, tracking actions, and delete.
  • Preview databases are provisioned, migrated, and cleaned through CI.
  • The local D1 adapter mirrors the production contract.
Input

Deterministic first

  • CSV aliases and CargoWise spreadsheets use predictable parsing.
  • Unrecognized shapes can fall back to configured OpenAI or Anthropic normalization.
  • Users review server-generated rows before confirmation.
Operations

Scheduled tracking and context

  • SafeCube polling is bounded and state-aware.
  • LOCODE normalization joins route progress to news and forecasts.
  • Stop and restart controls preserve owner isolation.
Cutover

Legacy route removed

  • The old /shipment/:po page and its UI modules are gone.
  • /shipments becomes the supported navigation target.
  • Shipment alert and notification behavior remains available in the new platform.

Review findings that changed the result

Three correctness failures were repaired at their real boundaries. Three secondary defects found during verification were also fixed.

Cause: the adapter schema came from the provider sandbox and treated fields as stricter than live responses. Fix: rebuild the boundary from six live captures, keep three real dated fixtures, and admit only the observed nullable variants. Blast radius: every scheduled enrichment attempt for real cargo.
Cause: D1 counted both the shipment and cascaded enrichment row, while success required exactly one changed row. Fix: keep the owner-scoped delete predicate unchanged and accept any positive change count. Blast radius: deletion of every shipment with enrichment.
Cause: context parsing accepted strings only, though provider vessel identifiers can be numbers. Fix: normalize numeric identifiers at the context parse boundary. Blast radius: AIS and vessel context for otherwise valid enriched shipments.
The loading state lost its visible headline geometry. The layout now keeps a readable width through the skeleton-to-content transition.
Failure artifacts included browser traces carrying session state. The acceptance workflow no longer uploads authenticated traces or videos.
Signed-in colleagues behind one egress IP competed for the anonymous IP budget. Authenticated traffic now uses a larger account-scoped budget, while pre-auth protection remains IP-scoped.

Verification architecture and outcomes

The result combines static gates, deployed acceptance, real-provider QA, and four independent final reviews.

Plan completion
24 / 24Implementation and final verification tasks complete.
F1
APPROVEPlan compliance
F2
APPROVECode quality
F3
APPROVEDeployed manual QA
F4
APPROVEScope fidelity
708 / 708

Unit suite

194 / 194

Supplementary suite

19 / 19

Python deployment tests

Clean

TypeScript and Vite build

Last green maintained acceptance
13 passed

Run 31982489540 completed against the deployed Worker at 40a2c13b.

Login and onboarding
CRUD and import
Tracking controls
Responsive flows
F3 real-container QA

HLXU1197025

CNSHG → ESBCN

Provider enrichment populated in 14m32s. AIS fallback was correct, and responses were confirmed private with no-store caching.

Exact-head result. Post-merge run 31998235394 received runner 1000004284 at feature head dd350bec. Steps 1 through 16 succeeded, including checkout, frontend build, Workers Paid verification, provider secrets, D1 setup and migrations, Worker deployment, cron trigger verification, and preview auth sync. Step 17 failed only while removing the preview Worker because PR #64 was already closed, so preview acceptance was skipped. Exact-head deployment is verified. Exact-head maintained acceptance remains unavailable, and this page does not claim otherwise. The owner explicitly authorized proceeding with that narrow gap.
Merged outcome

Merged after 24 / 24 and four approvals

Exact-head deployment succeeded through cron verification. Maintained acceptance at that head was skipped after PR closure; the last green run remains 31982489540 at 40a2c13b, with 13 passed.

F1 F2 F3 F4 approve