Auction Announcement / Declaration Flow v1

Scope

This implementation introduces the manual human-driven declaration path for auctions without rewriting the broader auction lifecycle. The source of truth is services/svc-tenders. services/api remains a compatibility/demo path.

Supported declaration states

• DRAFT
• READY_FOR_ANNOUNCEMENT
• ANNOUNCED

Supported transitions in v1:

• DRAFT -> READY_FOR_ANNOUNCEMENT
• READY_FOR_ANNOUNCEMENT -> ANNOUNCED

Direct DRAFT -> ANNOUNCED is intentionally not supported.

Manual input model

The form/domain payload is grouped into:

• identity
• subject
• commercial terms
• timeline
• participation rules
• evidence references
• governance metadata

Evidence in v1 is reference-only. No file storage/upload orchestration is introduced.

Domain normalization

packages/core/auction/declaration.ts defines:

• AuctionAnnouncementFormData
• DeclareAuctionCommand
• AuctionAnnouncementValidationResult
• AuctionReadinessChecklistItem
• AuctionAnnouncementPreview
• AuctionAnnouncedEvent
• declaration guards:
  • canMarkReady
  • canDeclareAuction

The service normalizes the raw form payload before persistence or transition.

Validation layers

services/svc-tenders/src/validation.ts implements:

1. field-level validation via zod
2. business/readiness validation via buildAuctionAnnouncementValidationResult
3. permission/governance shape validation via actor/capability checks

Readiness covers:

• identity completeness
• subject completeness
• commercial coherence
• bidding/delivery timeline coherence
• participation rule completeness
• evidence references present
• governance metadata present
• actor/capability presence

Persistence model

auction_declarations remains the workflow/declaration source of truth. It stores:

• auction_declarations
• auction_declaration_events

The declaration row keeps:

• JSONB form payload snapshot
• JSONB readiness snapshot
• JSONB preview snapshot
• JSONB declaration metadata
• state
• ready/declared actor + timestamps

auctions is the broader registry projection across internal lifecycle states. Declaration workflow now projects into auctions at three points:

• draft creation -> DRAFT
• mark ready -> READY_FOR_ANNOUNCEMENT
• declare -> ANNOUNCED

Draft/ready registry rows intentionally preserve true missing values as null where the draft is still incomplete.

For v1 projection compatibility:

• owner_stakeholder_id is sourced from explicit identity.ownerStakeholderId
• public subject linkage requires one real reference from linkedAssetId | linkedLotId | linkedTenderId
• organizationId remains declaration metadata only
• workflowTemplateId remains declaration metadata only
• linked_kes_contract_id stays null until a real KES/contract identifier exists
• minBid is temporarily projected from basePrice

Public auction routes filter out internal-only states:

• DRAFT
• READY_FOR_ANNOUNCEMENT

Internal/admin auction routes expose the broader registry, including those internal states, behind the existing declaration capability gate.

Optional output allocation linkage

Output Allocation is an optional upstream commercial source in v1.

• auction_declarations.allocation_id is nullable
• direct declarations continue to work with no allocation selected
• allocation-backed declarations can later prefill subject/origin/quantity context without replacing the declaration workflow
• declaration readiness, mark-ready, and declare do not require allocation presence in v1

Event / audit shape

Two declaration events are currently recorded:

• AUCTION_READY_FOR_ANNOUNCEMENT
• AUCTION_DECLARED

The declaration event includes:

• auctionId
• previousState
• newState
• declaredBy
• declaredAt
• normalized snapshot
• linked evidence
• rulesVersion
• intentId
• sourceSystem

This is intentionally shaped so the same semantics can later feed outbox/KES integration.

Future KES mapping points

Later KES automation should map to the same semantics:

• form payload -> normalized declaration snapshot
• readiness check -> deterministic workflow gate
• mark ready -> explicit state transition
• declare -> explicit state transition + event emission

The intended future mapping is:

• KES action triggers the same normalized DeclareAuctionCommand
• service executes the same readiness/guard logic
• resulting declaration event can feed projections and hashable workflow snapshots

Deferred items

• dedicated web wizard
• gateway proxying for declaration endpoints
• full auction lifecycle naming cleanup
• file upload/storage for evidence
• smart-contract / KES automation execution