--- id: SVC-CMT-MTG-recruitment title: Opening and Nomination Service product_area: committees module: meetings repository: services-committees source_module: modules/recruitment revision: 1 status: draft design_intent: proposed implementation_evidence: inconsistent inference: [] source_sha: services-committees: 36129c24daeaadcdb339218c38cdeaff9861359d owns: - DOM-CMT-MTG-005 - DOM-CMT-MTG-006 does_not_own: - >- The committee module owns seats, positions, terms and appointments and provides the operations used by review consequences. - >- The decisions service owns slate motions; closing their appointment consequence writes elected nominations. - >- The decisions service owns disclosure obligations, though the shared recruitment review handler writes their outcome. - >- Submissions owns forms and review decisions, and Volunteers owns the proposed opportunity integration that remains unbuilt. operations: - operation_id: getRecruitmentHealth intent: Answer a public availability probe for the recruitment API. access: public permission: >- none: the shared health route (the operation name follows the getHealth pattern of the route library) realises: [] published_to_submissions: 'not published: availability monitoring is outside submitted-data intake.' - operation_id: listCommitteeOpenings intent: >- Browse openings by selected committee and status, oldest first with keyset paging. access: console permission: committees.openings.read realises: - CAP-CMT-MTG-016 published_to_submissions: 'not published: this read has no submitted-data input contract.' - operation_id: createCommitteeOpening intent: >- Draft a vacancy offering for an optional seat or position with place count, dates and description. access: console permission: committees.openings.manage realises: - CAP-CMT-MTG-016 published_to_submissions: >- not published: this staff action uses the direct governance or recruitment API; the publication boundary remains proposed. - operation_id: createOpeningsFromForecast intent: >- Draft openings for selected forecast holders and report entries skipped by the rules. access: console permission: committees.openings.manage realises: - CAP-CMT-MTG-017 published_to_submissions: >- not published: this staff action uses the direct governance or recruitment API; the publication boundary remains proposed. - operation_id: getCommitteeOpening intent: Read the vacancy record together with its member interest count. access: console permission: committees.openings.read realises: - CAP-CMT-MTG-016 published_to_submissions: 'not published: this read has no submitted-data input contract.' - operation_id: updateCommitteeOpening intent: >- Edit supplied draft or open vacancy fields at its read version while retaining omitted values. access: console permission: committees.openings.manage realises: - CAP-CMT-MTG-016 published_to_submissions: >- not published: this staff action uses the direct governance or recruitment API; the publication boundary remains proposed. - operation_id: publishCommitteeOpening intent: Publish draft recruitment and prepare chair and staff-liaison notices. access: console permission: committees.openings.manage realises: - CAP-CMT-MTG-016 published_to_submissions: >- not published: this staff action uses the direct governance or recruitment API; the publication boundary remains proposed. - operation_id: closeCommitteeOpening intent: End published recruitment through an explicit staff action. access: console permission: committees.openings.manage realises: - CAP-CMT-MTG-016 published_to_submissions: >- not published: this staff action uses the direct governance or recruitment API; the publication boundary remains proposed. - operation_id: cancelCommitteeOpening intent: Withdraw draft or published recruitment at its expected version. access: console permission: committees.openings.manage realises: - CAP-CMT-MTG-016 published_to_submissions: >- not published: this staff action uses the direct governance or recruitment API; the publication boundary remains proposed. - operation_id: listCommitteeOpeningInterests intent: Read the contacts interested in this opening and their recorded notes. access: console permission: committees.openings.read realises: - CAP-CMT-MTG-016 published_to_submissions: 'not published: this read has no submitted-data input contract.' - operation_id: getVacancyForecast intent: >- Calculate upcoming seat-holder departures with term-limit, successor and opening context. access: console permission: committees.openings.read realises: - CAP-CMT-MTG-017 published_to_submissions: 'not published: this read has no submitted-data input contract.' - operation_id: listCommitteeNominations intent: >- Browse candidate records by committee, opening and selected status filters. access: console permission: committees.nominations.read realises: - CAP-CMT-MTG-018 published_to_submissions: 'not published: this read has no submitted-data input contract.' - operation_id: createCommitteeNomination intent: >- Put forward a contact or a person named with an e-mail address for the selected committee and optional target. access: console permission: committees.nominations.manage realises: - CAP-CMT-MTG-018 published_to_submissions: >- not published: this staff action uses the direct governance or recruitment API; the publication boundary remains proposed. - operation_id: getCommitteeNomination intent: Read the candidate record and its linked slate decision summary. access: console permission: committees.nominations.read realises: - CAP-CMT-MTG-018 published_to_submissions: 'not published: this read has no submitted-data input contract.' - operation_id: updateCommitteeNomination intent: >- Edit supplied submitted or under-review candidate fields at the expected version. access: console permission: committees.nominations.manage realises: - CAP-CMT-MTG-018 published_to_submissions: >- not published: this staff action uses the direct governance or recruitment API; the publication boundary remains proposed. - operation_id: slateCommitteeNomination intent: >- Select a candidate for the slate and optionally create a draft or open appointment decision. access: console permission: committees.nominations.manage realises: - CAP-CMT-MTG-018 published_to_submissions: >- not published: this staff action uses the direct governance or recruitment API; the publication boundary remains proposed. - operation_id: declineCommitteeNomination intent: >- Reject a candidate and keep that candidate out of any pending slate consequence. access: console permission: committees.nominations.manage realises: - CAP-CMT-MTG-018 published_to_submissions: >- not published: this staff action uses the direct governance or recruitment API; the publication boundary remains proposed. - operation_id: withdrawCommitteeNomination intent: Withdraw a candidate and any linked draft or open slate decision. access: console permission: committees.nominations.manage realises: - CAP-CMT-MTG-018 published_to_submissions: >- not published: this staff action uses the direct governance or recruitment API; the publication boundary remains proposed. - operation_id: listCommitteeOpeningAlternates intent: Read reserve applicants still standing after delivered review outcomes. access: console permission: committees.openings.read realises: - CAP-CMT-MTG-019 published_to_submissions: 'not published: this read has no submitted-data input contract.' - operation_id: listPortalOpenings intent: >- Return published openings permitted by committee listings and deadlines with the member’s interest flags. access: portal permission: committees.rosters.read realises: - CAP-CMT-MTG-016 published_to_submissions: >- not published: the current member action uses direct authorization; an approved exemption from operation publication is unestablished. - operation_id: expressOpeningInterest intent: >- Record the member’s interest in a visible opening, replacing its note on repetition. access: portal permission: committees.portal.participate realises: - CAP-CMT-MTG-016 published_to_submissions: >- not published: the current member action uses direct authorization; an approved exemption from operation publication is unestablished. - operation_id: portalNominate intent: >- Put forward the member or another candidate, preparing consent notice work for a different contact nominee. access: portal permission: committees.portal.participate realises: - CAP-CMT-MTG-018 published_to_submissions: >- not published: the current member action uses direct authorization; an approved exemption from operation publication is unestablished. - operation_id: listPublicOpenings intent: Return publicly listed published openings whose deadline has not elapsed. access: public permission: 'none: public listings only' realises: - CAP-CMT-MTG-016 published_to_submissions: >- not published: this endpoint only reads a public projection or a token-authorized calendar. - operation_id: getPublicOpening intent: >- Read one published opening permitted by the public listing and deadline filters. access: public permission: 'none: public listings only' realises: - CAP-CMT-MTG-016 published_to_submissions: >- not published: this endpoint only reads a public projection or a token-authorized calendar. events: - name: committees.opening.published direction: produced when: Recruitment moves from draft to open. payload_summary: >- Opening and committee references, optional target seat and position, offered places, dates, status and eligibility rule with its scope chain. - name: committees.opening.closed direction: produced when: 'An open vacancy becomes closed, filled or cancelled.' payload_summary: >- Opening and committee references, optional target seat and position, offered places, dates, status and eligibility rule with its scope chain. - name: committees.appointment.started direction: consumed when: The native subscriber receives a committed appointment start. payload_summary: >- Appointment and committee references, optional seat and position, and participation kind. - name: SubmissionDecisionDelivered version 1 direction: consumed when: >- The review receiver processes a decision for one of the four owned subject kinds. payload_summary: >- Review and submission references, subject, outcome kind and code, superseded decision, basis and acknowledgement link. jobs: - >- The committees_submission_decisions remote handler applies versioned reviews and drains acknowledgements after a new applied or refused outcome. - The decisions hourly job also drains outstanding owner acknowledgements. - >- No recruitment-specific scheduled closer exists; appointment events fill openings and deadlines only filter external reads. integrations: - system: Submissions direction: inbound contract: >- The version-one review receiver accepts four declared subject kinds and uses a seen-decision ledger for committed delivery deduplication. - system: Submissions direction: outbound contract: >- The outbox carries processed, deferred or rejected-by-owner outcomes after commit and retries unsuccessful acknowledgement sends; its production receiver port is unavailable. - system: Platform communications direction: outbound contract: >- Opening publication uses the existing notice ledger boundary, while nomination consent preparation has no local recovery ledger. - system: Volunteers direction: outbound contract: >- Only an opportunity reference is stored; no Volunteers call is implemented. - system: Platform Queries direction: outbound contract: >- Opening and nomination query datasets use their respective read permissions. - system: Platform attention direction: outbound contract: >- The nomination-review definition is present but withheld from registration and sweeping. consistency: - rule: >- Staff changes lock and version-check openings or nominations; opening events and applicable notices share that transaction, while nominations emit no dedicated business event. kind: transactional compensation: A failed database step rolls back its enclosing staff action. - rule: >- Review application commits supported supersession, consequence, seen ledger and acknowledgement together. kind: transactional compensation: >- A business refusal rolls that work back, then a separate transaction records owner rejection; the external review outcome remains unchanged. - rule: >- Appointment-started delivery updates openings only after the appointment itself has committed. kind: eventual compensation: >- Retries are safe for counting because each opening remembers appointments already applied. - rule: Owner acknowledgements are sent after their outcome transaction commits. kind: eventual compensation: >- Failed rows remain pending without an attempt cap, and expiring claims can permit repeated sends. - rule: >- Dissolution cancels editable openings and withdraws pending nominations and decisions inside its transaction. kind: transactional compensation: >- Any failed cleanup step prevents that database dissolution from committing. evidence: - >- services-committees at 36129c24: modules/recruitment/aws/api/recruitment.routes.ts, recruitment.schemas.ts; aws/logic/*.ts; services/**; ports/**; db/** - >- services-committees at 36129c24: aws/committees.service.ts (openings, nominations, rosters and portal permissions), aws/committees.submissions.ts, aws/committees.events.ts controls: - TC-IAM-001 - TC-IAM-002 - TC-IAM-004 - TC-IAM-005 - TC-IAM-006 - TC-AZ-001 - TC-AZ-002 - TC-AZ-003 - TC-AZ-004 - TC-AZ-006 - TC-TEN-001 - TC-TEN-002 - TC-TEN-003 - TC-TEN-004 - TC-SEC-001 - TC-SEC-002 - TC-SEC-003 - TC-SEC-004 - TC-CRY-001 - TC-CRY-002 - TC-CRY-003 - TC-CRY-004 - TC-DAT-001 - TC-DAT-002 - TC-DAT-003 - TC-DAT-004 - TC-DAT-007 - TC-LOG-002 - TC-LOG-003 - TC-LOG-004 - TC-LOG-005 - TC-AVL-002 - TC-AVL-003 - TC-AVL-004 - TC-AVL-005 - TC-MON-001 - TC-MON-002 - TC-MON-003 - TC-PI-001 - TC-PI-002 - TC-PI-003 - TC-PI-004 - TC-PI-005 - TC-PRV-001 - TC-PRV-002 - TC-PRV-004 --- # Opening and Nomination Service ## What This Service Is For This service follows committee recruitment from advertised vacancies and departure forecasts to nominated candidates and appointment slates. It also applies Submissions review outcomes to seat applications, nominations, appointment proposals and disclosures. Its work is deterministic and includes no inference. ## Boundary Openings and nominations are owned here. Appointments and targets belong to the committee module, while slate motions and declaration obligations belong to decisions. The shared review handler records supported effects through owner operations or the documented internal cross-module writes. ## Operations in Words Staff draft, publish and close openings, inspect interest and alternates and create drafts from a vacancy forecast. Candidate records can be edited, slated, declined or withdrawn. Member operations list allowed openings, express interest and nominate; public reads honor listings and deadlines. No inspected route publishes a Submissions operation binding, and approval of the proposed subject-kind alternative remains unestablished. ## Events and Jobs Opening publication and departure from open status create business events. The native appointment-started subscriber counts matching appointments toward filling. The remote review handler and decisions hourly job drain acknowledgement work; no scheduled job closes recruitment at its deadline. ## Consistency Guarantees Each explicit record mutation uses its lock and expected version. Seen-decision entries protect committed review redelivery, while irreversible supersession becomes a recorded owner refusal visible only in logs. Provider calls and acknowledgement delivery remain eventual, with unbounded retries and expiring claims rather than exclusive lifetime ownership.