Vendors & Liabilities

Vendors are external contractors or agencies tracked in VERA. Liabilities are fixed payment commitments to those vendors.

---

Vendor users

A vendor is a user with employment_type = "vendor".

add_user name="Dev House X" employment_type="vendor"

Vendor users are like regular users in the system — they appear in list_users, can be allocated to projects, and have time logged against them. The difference is:

1. PMs log hours on their behalf — vendor users don't message the bot themselves
2. Cost is typically governed by a liability rather than an hourly rate
3. Revenue is the same as direct labor — hours × billing_rate

---

Liabilities

A liability is a fixed payment commitment to a vendor on a specific project.

Example: "We agreed to pay Dev House X $5,000 to build the authentication module on Project Rambo."

This is recorded as a liability with:

• vendor_user_id — Dev House X's user ID
• project_id — Project Rambo
• agreed_amount — $5,000
• description — "Authentication module development"

Why liabilities exist

Without a liability, VERA calculates vendor cost as hours × hourly_cost. But for fixed-fee vendor engagements, that's wrong — you've agreed to pay $5,000 regardless of how many hours are logged.

A liability overrides the hourly calculation entirely. When a liability is active for vendor X on project Y, the cost for that vendor on that project is agreed_amount, not hours × rate. The two methods are never mixed.

Revenue still comes from hours

Liabilities only affect cost. Revenue is still recognised from time entries in the normal way (hours × billing_rate for T&M, or percentage-of-completion for Fixed Price).

---

Liability lifecycle

create_liability → active
       ↓
  cancel_liability → cancelled (not deleted)

Cancelled liabilities are kept for audit trail. When listing liabilities, filter by status = "active" to see open commitments only.

---

Permissions

Action	Owner	Manager	User
Create liability	✅	❌	❌
View liabilities	✅ (all)	✅ (own projects)	❌
Cancel liability	✅	❌	❌

---

P&L cost rule (vendor summary)

For vendor X on project Y:

  If active liability exists:
    cost = liability.agreed_amount

  Else:
    cost = hours_logged × hourly_cost (from Rate History, effective on entry date)

This rule is applied when calculating project cost and margin in generate_monthly_report and the reporting sheet's financial tabs.

---

Common vendor workflow

1. Add the vendor: add_user with employment_type="vendor"
2. Create a liability: create_liability with the agreed amount and description
3. PM logs hours: log_time with the vendor's user ID — this tracks delivery against the engagement
4. View cost: The liability's agreed_amount appears as cost in financial reports, regardless of hours logged

If the engagement grows beyond the original liability, cancel the old one and create a new one with the updated amount.