feat(orders): capture order cancellation as first-class record state

[jakubretajczykBD]

Summary

• handleSourceCancellation previously relayed a source cancellation to destinations and returned — nothing was written to the order record, so cancellation was invisible to SQL and only present in orderSnapshot.status if a later poll happened to re-ingest the order.
• Adds a nullable cancelledAt column on order_records, written once and preserved via an atomic COALESCE update (markCancelled) — a redelivered cancel event or a later re-poll can never overwrite an already-recorded instant.
• handleSourceCancellation now calls markCancelled before relaying to destinations; the write is best-effort (logged, not rethrown) so a transient DB error can never block the pre-existing relay behaviour.
• persistOrder/persistIncomingSnapshot (the ordinary polling/ingestion path, for sources that report status: 'cancelled' directly) record it through the same atomic markCancelled, called after upsert() rather than folded into it — upsert() never touches cancelledAt, so two ingestion paths (webhook + reconciliation poll) racing for the same order can't stomp each other's write. Verified empirically against a live Postgres that TypeORM's save() omits an undefined-left column from the generated UPDATE.
• OrderRecordFilters.cancelled + a findMany predicate make the fact queryable without parsing orderSnapshot; not wired into any HTTP filter or FE control yet — that's the aggregate endpoints' job ([IMPL] Backend — sales & channel aggregates endpoint (revenue, orders, AOV + median, units) #1987/[IMPL] Backend — top-products endpoint with inline per-channel split #1988).
• cancelledAt surfaced on OrderRecordResponseDto.
• Additive migration with a documented best-effort backfill (cancelledAt := updatedAt) for historical rows whose snapshot already reports 'cancelled'.

Context

• Plan: docs/plans/implementation-plan-order-cancellation-record-state.md
• Pre-implement gate: docs/plans/analysis/ANALYSIS-order-cancellation-record-state.md
• Part of the /analytics epic ([PRODUCT-DESIGN] Business analytics surface at /analytics — sales layer + cross-channel layer #1976) — this is dependency [C], blocking the order analytics read model ([IMPL] Backend — order analytics read model (queryable line items, placed-at, currency, tax treatment) #1985) from excluding cancelled orders.

Test plan

• Unit tests added across all touched layers (domain entity, pure helper removed in favor of the atomic-write redesign, repository, application service, ingestion service, controller) — all passing locally.
• pnpm --filter @openlinker/core type-check / pnpm --filter @openlinker/api type-check — clean.
• pnpm --filter @openlinker/core lint — clean (0 errors, pre-existing warnings only).
• pnpm check:invariants — all invariants pass, including migration-timestamp ordering vs origin/main.
• Migration applied + reverted + re-applied against the local dev Postgres; backfill confirmed against real pre-existing data.
• apps/api full lint run was interrupted locally mid-session — CI will confirm.
• Full pnpm test / pnpm test:integration

Closes #1984

🤖 Generated with Claude Code

[piotrswierzy]

Tech-lead review — ✅ Approve

Adds order_records.cancelledAt so a source-reported cancellation leaves a queryable trace instead of being visible only by parsing orderSnapshot. Both observation paths are covered — the dedicated cancel-event handler and the ordinary ingestion path where a feed simply reports status: 'cancelled'. The concurrency reasoning here is the strongest part of the PR and it's correct.

Verified

The central design call is right: cancellation is a new column, not a new recordStatus value. recordStatus tracks item-mapping resolution (ready / awaiting_mapping / source_deleted), and an order can legitimately be ready and cancelled at once. Modelling it as a status value would have been lossy and would have broken every exhaustive switch, health bucket, and list filter that consumes recordStatus. The order-record.entity.ts:67-74 comment says exactly this. This is also why the diff touches so few call sites for a change of this reach.

Single-writer discipline for the new column is genuinely airtight, and the non-obvious half is the omission. order-record.repository.ts:732-744 deliberately does not map cancelledAt in toOrm, so TypeORM omits the column from the generated statement entirely (the ORM property is declared cancelledAt!: Date | null with no initializer, so it stays undefined, and TypeORM skips undefined — unlike null). That matters because upsert() is an unlocked full-object save(), and per docs/architecture-overview.md § "Webhook = trigger, poll = reconciliation backstop" the webhook and reconciliation poll paths legitimately race for the same order. Mapping the column there would have let a stale in-memory read stomp a concurrently-committed value. Instead markCancelled is the sole writer, via COALESCE("cancelledAt", $1) (repository.ts:558-565) — atomic, first-write-wins, no read-before-write. A redelivered cancel event is a genuine no-op, not a last-write-wins overwrite of the first-observed instant.

Ordering in recordCancellationIfNeeded is deliberate and correct (order-record.service.ts:270-278): called after upsert(), never before, precisely because upsert() cannot carry the column. The follow-up findById is needed because upsert()'s return value can't reflect a column it never sent, and the extra read is paid only on the rare cancelled path. Both facts are stated in the comment rather than left for a reader to rediscover.

Migration is correct on every axis I checked:

• Timestamp 1832000000008 is strictly greater than origin/main's current tail (1832000000007), per the synthetic-sequential rule in docs/migrations.md § Timestamp uniqueness invariant rule 3 — verified against git ls-tree origin/main, not assumed.
• Class suffix AddOrderRecordCancelledAt1832000000008 matches the filename prefix.
• up() and down() both present, both fully IF [NOT] EXISTS-guarded, so a re-run or from-scratch replay is a no-op.
• The backfill is idempotent (WHERE "cancelledAt" IS NULL) and — importantly — honest about its own imprecision: it uses updatedAt as an explicitly-labelled proxy and says in the header that the true cancellation instant is unreconstructable from data OL holds. That's the right way to ship a lossy backfill.
• Index on cancelledAt supports the IS [NOT] NULL predicate the aggregate endpoints will need.

Error handling on the relay path is the right trade-off (order-ingestion.service.ts:517-534): markCancelled is attempted before the relay so a throwing relay can't skip the record write, and its own failure is logged-not-rethrown so a transient DB error cannot stop the cancel reaching the destination shop. The pre-existing behaviour is the one that must not regress, and the comment names that reasoning.

Test coverage is proportionate — unit specs at the entity, service, and repository layers plus a dedicated order-cancellation-record-state.int-spec.ts for the vertical slice. isCancelled is a pure getter over an already-loaded field, which is inside the ADR-011 allowance.

SUGGESTION

• Merge-order note, not a defect: #2046 (return/refund/withdrawal records) is in flight and will likely also claim a 1832000000008/…009 prefix. Whichever lands second needs a re-prefix — pnpm lint will catch it via check-migration-timestamps.mjs, but worth coordinating so it isn't discovered at the pre-commit hook.
• cancelledAt is set-once and never cleared by design. If any source can un-cancel an order (Allegro can't, but a shop source conceivably could), the record would stay cancelled permanently. Worth one line in the entity doc stating that no un-cancel path exists yet, so a future reader knows it's an unhandled case rather than an oversight.
• The swallowed markCancelled failure leaves the record queryable as non-cancelled with only a log line, self-healing on the next re-poll. Fine today; once #1987/#1988 surface cancellation counts to operators, that silent divergence becomes worth a metric rather than just a log.
• OrderRecordFilters.cancelled ships unwired to any HTTP param — correctly scoped to #1987/#1988 and documented as such. No action, just noting the deliberate dead-until-consumed surface.

Merge readiness: ✅ Approve — correct model, airtight single-writer concurrency story, and a properly guarded idempotent migration.