-- allium: 3
-- interview-scheduling.allium

-- Scope: Interview scheduling flow only
-- Includes: Candidacy, Interview, InterviewSlot, Invitation, Feedback
-- Excludes:
--   - User authentication (use auth library spec)
--   - Analytics/reporting (separate spec)
--   - Legacy V1 API (deprecated, not specified)
--   - Greenhouse sync (use greenhouse library spec)

undefined

invitation = Invitation(
    candidate_id=candidate_id,
    token=secrets.token_urlsafe(32),
    expires_at=datetime.utcnow() + timedelta(days=7),
    status='pending'
)
db.session.add(invitation)

for slot in slots:
    slot.status = 'proposed'
    invitation.slots.append(slot)

db.session.commit()

send_email(
    to=candidate.email,
    template='interview_invitation',
    context={'invitation': invitation, 'slots': slots}
)

return invitation

undefined

requires: slots.all(s => s.status = confirmed)

ensures:
    for s in slots:
        s.status = proposed
ensures: Invitation.created(
    candidacy: candidacy,
    slots: slots,
    expires_at: now + 7.days,
    status: pending
)
ensures: Email.created(
    to: candidacy.candidate.email,
    template: interview_invitation
)

What we dropped:
- `candidate_id: int` became just `candidacy`
- `db.session.query(...)` became relationship traversal
- `secrets.token_urlsafe(32)` removed entirely (token is implementation)
- `datetime.utcnow() + timedelta(...)` became `now + 7.days`
- `db.session.add/commit` implied by `created`
- `invitation.slots.append(slot)` implied by relationship

OAUTH_PROVIDERS = {
    'google': GoogleOAuthProvider(client_id=..., client_secret=...),
}

def authenticate(provider: str, code: str) -> User:
    return OAUTH_PROVIDERS[provider].authenticate(code)

from sqlalchemy.dialects.postgresql import JSONB, ARRAY

class Candidate(Base):
    skills = Column(ARRAY(String))
    metadata = Column(JSONB)

entity Candidate {
    skills: Set<String>
    metadata: String?              -- or model specific fields
}

class GreenhouseSync:
    def import_candidate(self, greenhouse_id: str) -> Candidate:
        data = self.client.get_candidate(greenhouse_id)
        return Candidate(
            name=data['name'],
            email=data['email'],
            greenhouse_id=greenhouse_id,
            source='greenhouse'
        )

external entity Candidate {
    name: String
    email: String
    source: CandidateSource
}

external entity Candidate {
    name: String
    email: String
    greenhouse_id: String?  -- explicitly modeled
}

rule SyncFromGreenhouse {
    when: GreenhouseWebhookReceived(candidate_data)
    ensures: Candidate.created(
        ...
        greenhouse_id: candidate_data.id
    )
}

Entry points:
  - API: /api/candidates/*, /api/interviews/*, /api/invitations/*
  - Webhooks: /webhooks/greenhouse, /webhooks/calendar
  - Jobs: send_reminders, expire_invitations, sync_calendars

Models:
  - Candidate, Interview, InterviewSlot, Invitation, Feedback

Services:
  - SchedulingService, NotificationService, CalendarService

Integrations:
  - Google Calendar, Slack, Greenhouse, SendGrid

class Invitation(Base):
    status = Column(Enum('pending', 'accepted', 'declined', 'expired'))

entity Invitation {
    status: pending | accepted | declined | expired
}

def accept_invitation(invitation_id: int, slot_id: int):
    invitation = get_invitation(invitation_id)

    if invitation.status != 'pending':
        raise InvalidStateError()
    if invitation.expires_at < datetime.utcnow():
        raise ExpiredError()

    slot = get_slot(slot_id)
    if slot not in invitation.slots:
        raise InvalidSlotError()

    invitation.status = 'accepted'
    slot.status = 'booked'

    # Release other slots
    for other_slot in invitation.slots:
        if other_slot.id != slot_id:
            other_slot.status = 'available'

    # Create the interview
    interview = Interview(
        candidate_id=invitation.candidate_id,
        slot_id=slot_id,
        status='scheduled'
    )

    notify_interviewers(interview)
    send_confirmation_email(invitation.candidate, interview)

rule CandidateAcceptsInvitation {
    when: CandidateAccepts(invitation, slot)

    requires: invitation.status = pending
    requires: invitation.expires_at > now
    requires: slot in invitation.slots

    ensures: invitation.status = accepted
    ensures: slot.status = booked
    ensures:
        for s in invitation.slots:
            if s != slot: s.status = available
    ensures: Interview.created(
        candidacy: invitation.candidacy,
        slot: slot,
        status: scheduled
    )
    ensures: Notification.created(to: slot.interviewers, ...)
    ensures: Email.created(to: invitation.candidate.email, ...)
}

undefined

for invitation in expired:
    invitation.status = 'expired'
    for slot in invitation.slots:
        slot.status = 'available'
    notify_candidate_expired(invitation)

for interview in upcoming:
    send_reminder_notification(interview)

Extract:

ensures: invitation.status = expired
ensures:
    for s in invitation.slots:
        s.status = available
ensures: CandidateInformed(candidate: invitation.candidate, about: invitation_expired)

ensures: Notification.created(to: interview.interviewers, template: reminder)

undefined

undefined

if not candidate:
    candidate = Candidate(greenhouse_id=webhook_data['id'])

candidate.name = webhook_data['name']
candidate.email = webhook_data['email']

Suggests:

When repeated interface patterns appear across service boundaries (e.g. the same serialisation contract expected by multiple consumers), these suggest `contract` declarations for reuse rather than duplicated inline obligation blocks.

entity Invitation {
    candidate_id: Integer
    token: String(32)
    created_at: DateTime
    expires_at: DateTime
    status: pending | accepted | declined | expired
}

entity Invitation {
    candidacy: Candidacy
    created_at: Timestamp
    expires_at: Timestamp
    status: pending | accepted | declined | expired

    is_expired: expires_at <= now
}

undefined

**Generic patterns with specific providers:**
- OAuth flows (Google, Microsoft, GitHub)
- Payment processing (Stripe, PayPal)
- Email delivery (SendGrid, Postmark, SES)
- Calendar sync (Google Calendar, Outlook)
- ATS integrations (Greenhouse, Lever)
- File storage (S3, GCS)

**Configuration-driven integrations:**
```python

undefined

use "github.com/allium-specs/stripe-billing/abc123" as stripe

-- Application responds to Stripe events
rule ActivateSubscription {
    when: stripe/PaymentSucceeded(invoice)
    ...
}

-- greenhouse-ats.allium (library spec)
-- Specifies: Greenhouse webhook events, candidate sync, etc.

-- interview-scheduling.allium (application spec)
use "./greenhouse-ats.allium" as greenhouse

rule ImportCandidate {
    when: greenhouse/CandidateCreated(data)
    ensures: Candidacy.created(...)
}

-- Don't specify Slack details, just:
ensures: Notification.created(
    to: interviewers,
    channel: slack
)

-- TOO DETAILED - this is Stripe's domain, not yours
rule ProcessStripeWebhook {
    when: WebhookReceived(payload, signature)

    requires: verify_stripe_signature(payload, signature)

    let event = parse_stripe_event(payload)

    if event.type = "invoice.paid":
        ...
}

-- Application responds to payment events (integration handled elsewhere)
rule PaymentReceived {
    when: stripe/InvoicePaid(invoice)
    ...
}

-- BAD: Acknowledges duplication without resolving it
-- Order vs Purchase
-- checkout.allium uses "Purchase" - these are equivalent concepts.

undefined

The implicit states are:
- `pending`: requested_at set, feedback_id null, reminded_at null
- `reminded`: reminded_at set, feedback_id null
- `submitted`: feedback_id set

Extract to explicit:

undefined

undefined

Consolidate into one rule:

requires: invitation.status = pending
requires: invitation.expires_at > now
requires: slot in invitation.slots
...

undefined

def send_notification(user, message):
    try:
        slack.send(user.slack_id, message)
    except SlackError:
        pass  # Silently ignore failures

ensures: Notification.created(to: user, channel: slack)

public interface NotificationStrategy {
    void notify(NotificationContext context);
}

public class SlackNotificationStrategy implements NotificationStrategy {
    @Override
    public void notify(NotificationContext context) {
        // Actual Slack call buried 5 levels deep
    }
}