RES

Consultancies live and die on staffing decisions. Over-allocate Linh by 20% and she ships late on two projects; under-allocate Minh by 50% and you are paying for capacity that is not generating revenue. The traditional toolchain is a spreadsheet that goes stale within a week, a Gantt tool that does not know about timesheets, and a hiring plan that exists only in the CEO's head. RES collapses the three into one — an allocation matrix that is always sourced from current data, a Gantt that respects timesheets and skill mastery, and a hiring forecast that is generated, not narrated.

The bet is that a services org with a clean allocation matrix can answer staffing questions in seconds rather than days — and that the same matrix, augmented with forecast curves from CRM (pipeline win-rate × project size) and OKR (Q3 hiring objective), becomes the substrate of a hiring forecast that is concrete, dated, and signable. RES turns "we should probably hire a senior Rust person at some point" into "we will be capacity-short by 60 h / week starting 2026-08-12 on backend skills; backfilling requires hire by 2026-06-25 given 90-day average ramp."

A structured decomposition of RES's scope. Every cell traces back to PRD §9.18 + SRS §7.18.

RES is a Rust service that consumes events from four upstream modules, maintains a materialised-view-backed allocation matrix, and exposes both a federated GraphQL subgraph and a thin gRPC API for the COO-skill. The Gantt UI is a TypeScript SPA with Yjs CRDT for multi-user drag-drop. Every write to res.allocation emits an audit row to BRAIN and triggers downstream materialised-view refresh.

Internal components

The core RES table is res.allocation — an append-only record of "Member X is allocated H hours to Project P during week W." A materialised view res.allocation_matrix rolls these up by (member, week) for the hot-path read. Capacity, forecast, skill-gap, hiring-plan, and conflict are derived tables driven by event-time refresh.

Allocation matrix view (materialised)

CREATE MATERIALIZED VIEW res.allocation_matrix AS
SELECT
  m.tenant_id,
  m.id AS member_id,
  m.display_name,
  c.week_start,
  c.available_hours,
  COALESCE(SUM(a.planned_hours) FILTER (WHERE a.allocation_type = 'billable'), 0) AS billable_h,
  COALESCE(SUM(a.planned_hours) FILTER (WHERE a.allocation_type = 'non_billable'), 0) AS non_billable_h,
  COALESCE(SUM(a.planned_hours), 0) AS total_planned_h,
  CASE
    WHEN c.available_hours = 0 THEN NULL
    ELSE COALESCE(SUM(a.planned_hours), 0) / c.available_hours
  END AS utilisation
FROM res.member m
JOIN res.capacity c ON c.member_id = m.id
LEFT JOIN res.allocation a ON a.member_id = m.id AND a.week_start = c.week_start
WHERE m.active
  AND c.week_start BETWEEN now()::date - interval '4 weeks'
                       AND now()::date + interval '26 weeks'
GROUP BY m.tenant_id, m.id, m.display_name, c.week_start, c.available_hours;

CREATE UNIQUE INDEX ON res.allocation_matrix (tenant_id, member_id, week_start);

-- Refresh trigger: LISTEN/NOTIFY from event_ingest.rs
-- Each upstream event narrows the refresh window to affected (member, week) keys.

Three surfaces: a federated GraphQL subgraph for the Gantt SPA + cross-module reads, a thin gRPC API for agent-skill recommendations, and an MCP tool catalogue for natural-language allocation editing through Genie.

GraphQL subgraph (federated)

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@external", "@shareable", "@requiresScopes"])

type Allocation @key(fields: "id") {
  id: ID!
  tenantId: ID!
  member: Member!
  project: Project!
  weekStart: Date!
  plannedHours: Float!
  allocationType: AllocationType!
  createdAt: DateTime!
}

type Capacity @key(fields: "memberId weekStart") {
  memberId: ID!
  weekStart: Date!
  availableHours: Float!
  status: CapacityStatus!
  ytdOvertimeHours: Float!
}

type ForecastedNeed {
  projectId: ID!
  skillId: ID!
  weekStart: Date!
  demandedHours: Float!
  weightedHours: Float!
}

type SkillGap {
  skillId: ID!
  weekStart: Date!
  demandHours: Float!
  supplyHours: Float!
  gapHours: Float!
}

type HiringPlan @key(fields: "id") {
  id: ID!
  skill: Skill!
  roleTier: String!
  headcountToAdd: Int!
  targetHireDate: Date!
  coverageHoursPerWeek: Float!
  status: HiringPlanStatus!
}

type ConflictRecord @key(fields: "id") {
  id: ID!
  memberId: ID!
  weekStart: Date!
  kind: ConflictKind!
  severity: Severity!
  status: ConflictStatus!
  detectedAt: DateTime!
}

enum AllocationType { BILLABLE NON_BILLABLE TRAINING LEAVE }
enum CapacityStatus { ACTIVE SABBATICAL LEAVE HOLIDAY }
enum ConflictKind { OVER_ALLOC UNDER_ALLOC OT_CAP_BREACH SKILL_MISMATCH }
enum Severity { WARN BLOCK }
enum ConflictStatus { OPEN ACKNOWLEDGED RESOLVED }
enum HiringPlanStatus { DRAFT APPROVED SOURCING FILLED }

extend type Member @key(fields: "id") {
  id: ID! @external
  allocations(from: Date, to: Date): [Allocation!]! @requiresScopes(scopes: [["res.read"]])
  capacityByWeek(weekStart: Date!): Capacity @requiresScopes(scopes: [["res.read"]])
}

extend type Project @key(fields: "id") {
  id: ID! @external
  allocations(from: Date, to: Date): [Allocation!]! @requiresScopes(scopes: [["res.read"]])
  forecastedNeeds(from: Date, to: Date): [ForecastedNeed!]! @requiresScopes(scopes: [["res.read"]])
}

type Query {
  allocationMatrix(memberIds: [ID!], from: Date!, to: Date!): [Allocation!]!
    @requiresScopes(scopes: [["res.read"]])
  conflicts(memberId: ID, status: ConflictStatus, kind: ConflictKind): [ConflictRecord!]!
    @requiresScopes(scopes: [["res.read"]])
  skillsGap(from: Date!, to: Date!, family: String): [SkillGap!]!
    @requiresScopes(scopes: [["res.read"]])
  hiringPlans(status: HiringPlanStatus): [HiringPlan!]!
    @requiresScopes(scopes: [["res.read"]])
}

type Mutation {
  upsertAllocation(input: AllocationInput!): Allocation!
    @requiresScopes(scopes: [["res.write_allocation"]])
  deleteAllocation(id: ID!): Boolean!
    @requiresScopes(scopes: [["res.write_allocation"]])
  approveHiringPlan(id: ID!): HiringPlan!
    @requiresScopes(scopes: [["res.approve_hiring"]])
  acknowledgeConflict(id: ID!, note: String): ConflictRecord!
    @requiresScopes(scopes: [["res.write_allocation"]])
}

input AllocationInput {
  memberId: ID!
  projectId: ID!
  weekStart: Date!
  plannedHours: Float!
  allocationType: AllocationType!
}

REST endpoints (admin + report)

MCP tool catalogue

Flow 1 — Allocate a Member to a project (drag-drop)

Flow 2 — Detect over-allocation (background)

Flow 3 — Generate hiring forecast (nightly)

Flow 4 — Skills-gap analysis

Flow 5 — Reallocation (project priorities shift)

An allocation row traverses six states from draft to completed; conflict states branch off at any point. Every transition writes a chained audit row to BRAIN.

Per-state actions

RES NFRs cover Gantt interaction latency, matrix freshness, OT-cap correctness, and reallocation-suggestion accuracy.

RES is downstream of four data-producing modules (HR, PROJ, TIME, LEARN) plus CRM for pipeline probabilities, and is consumed by OKR (hiring objective) and the COO daily flow.

RES touches employment data — staffing decisions, overtime computation, hiring forecasts — placing it in Annex III §4 (employment) territory under the EU AI Act and squarely inside Vietnamese Labor Code compliance.

RES-specific risks tracked in the risk register.

RES health rolls up into 10 KPIs covering utilisation, conflict rate, forecast accuracy, and OT-cap compliance.

RES is owned by the COO seat with CHRO consulted on allocation policy. Today (COO vacant), CEO is interim accountable.

Admin CLI cyberos-res for COO / CHRO seat operators. Every destructive command writes a chained BRAIN audit row before exit.

1. Show capacity vs forecast for the next 12 weeks

$ cyberos-res matrix --from 2026-W21 --weeks 12 --format table

WEEK    MEMBER       CAP    PLANNED  BILLABLE  ACTUAL  UTIL
W21     Linh         40h    44h      36h       —       110%  ⚠
W21     Minh         40h    18h      18h       —        45%  ⚠
W21     Khanh        40h    32h      28h       —        80%
W22     Linh         40h    38h      30h       —        95%
…

2. Find staffable Members for a project

$ cyberos-res find-staffable \
    --project proj-atlas \
    --skills rust,postgres,react \
    --weeks 2026-W23..2026-W30 \
    --hours-per-week 16

[ranked candidates]
  1. Linh    mastery: rust=4 postgres=4 react=3   slack=22h/wk avg   score=92
  2. Khanh   mastery: rust=3 postgres=5 react=4   slack=18h/wk avg   score=86
  3. Anh     mastery: rust=2 postgres=3 react=5   slack=24h/wk avg   score=74

3. Generate a hiring forecast

$ cyberos-res hiring-forecast --horizon 26w --output draft

[hiring plan · draft]
  skill=rust     tier=T3   need=1   target_hire=2026-08-25   coverage=24h/wk
  skill=design   tier=T2   need=1   target_hire=2026-09-15   coverage=18h/wk

[rationale]
  rust: forecast 96h/wk by 2026-W36; supply 60h/wk after Linh's parental leave
        gap opens 2026-W34; with 8wk ramp + 4wk hire cycle → target 2026-08-25
  design: forecast 36h/wk by 2026-W39; supply 18h/wk; gap opens 2026-W37
        → target 2026-09-15

[audit]  brain seq=88412 chain=a3f2…9d8e

4. Suggest reallocation for a conflict

$ cyberos-res reallocate --conflict CR-001834

[conflict] Linh @ W23: planned=44h capacity=40h util=110%

[suggestion 1]  move 4h "atlas-api-12" → Khanh (mastery=4, slack=12h)
[suggestion 2]  defer 4h "cygnus-m2"   → W24 (project allows; PM approved)
[suggestion 3]  trim 4h "atlas-api-12" (issue overestimated; TIME calibration says -25%)

→ apply [1] [2] [3] or [n]one ? _

5. List unresolved conflicts

$ cyberos-res conflicts list --status open --severity block

CR-001834  2026-05-13  Linh    W23  over_alloc       util=110%  severity=warn
CR-001841  2026-05-14  Khanh   W24  ot_cap_breach    proj_ot=212h cap=200h severity=block ⛔

6. Per-Member timeline (DSAR-style)

$ cyberos-res member-timeline --subject linh@cyberskill.com --weeks 13

WEEK     PLANNED  ACTUAL  PROJECTS                     STATUS
2026-W23 44h      —       atlas(28) · cygnus(16)        proposed
2026-W22 38h      36h     atlas(24) · cygnus(14)        completed
2026-W21 40h      41h     atlas(20) · cygnus(16) · L(4) completed
…

7. DSAR export for a Member

$ cyberos-res dsar-export --subject linh@cyberskill.com --output dsar.zip

[dsar] allocations:  624 rows (104 weeks)
[dsar] capacity:     104 rows
[dsar] conflicts:    18 rows
[dsar] member_skill: 24 rows
[dsar] written:      dsar.zip (188 KB)