💎

REW

P1 · Total Rewards Planned · P1 design phase Owner: HR/Ops + CEO

The legal heart of the social contract. 3P income (P1 Base + P2 Allowance + P3 Performance), an inflation-protected BP ledger, anti-retroactive parameter versioning, and a P1-protection invariant that cannot be violated even by accident.

REW encodes the Total Rewards & Career Path Appendix exactly. It is "Bet 5" in the PRD: a moat. The three-component 3P model decomposes monthly pay into P1 (Base, cash, contractually guaranteed), P2 (Allowance, cash, role-tier-based), and P3 (Performance, cash overflow from bonus pool). The BP (Bonus Points) ledger is a unit-of-account ledger with anti-inflation interest pegged to the ACB savings rate. Two hard invariants make this module legally distinctive: (1) the system never reduces P1 base salary in cash as a result of an evaluation — even a bad performance review cannot trigger a P1 cut; and (2) published parameter versions are immutable — recomputing an old payslip against the parameters effective at that period_end must yield byte-identical output forever. Compensation values are structurally excluded from BRAIN ingestion (DEC-036). The module is EU AI Act Annex III §4 high-risk because payroll computation is employment-decision automation. PRD §9.14 locks the FRs; SRS §4.14 binds them to verification methods.

REW is the compensation computation and ledger plane — the place where Total Rewards parameters become payslips, and where every payslip is reproducible byte-for-byte from the parameters that were effective at its period_end. The cash side is split into P1 (Base), P2 (Allowance), and P3 (Performance overflow from the BP fund). The non-cash side — BP (Bonus Points), an inflation-indexed unit of account — runs as an append-only ledger. The hard rule across the board: append-only, no mutations. Amendments are supersession rows; corrections are reversal rows. The 10-year statutory retention is enforced at the storage layer (S3 object-lock) so even a malicious admin cannot back-date a payslip.

Invariant — P1 protection

The system MUST NOT propose a reduction to P1 base salary in cash as the output of any evaluation. Performance review outcomes can withhold P3 (Performance) and adjust P2 (Allowance) tiers, but P1 in cash terms is contractually protected. Violation = sev-0. Hard system property; enforced as a constraint check on every compensation_change row.

Invariant — anti-retroactive parameter versioning

Published parameter versions are immutable. A recompute of any old payslip — say, January 2024 — against the parameters effective at 2024-01-31 23:59:59 UTC must produce a byte-identical PDF. Parameter rows have effective_to + superseded_by; never UPDATE. Violation = sev-0. Verified by a CI replay job that recomputes the last 24 months' payslips at every parameter change.

Status
Planned
P1 · design phase
Est. LoC
~6,800
Rust (axum) + computation kernel
Planned tests
140+
incl. determinism replay suite
3P split
P1 + P2 + P3
Base · Allowance · Performance
BP interest
ACB rate
VND inflation-pegged
BRAIN ingestion
= 0
structural exclusion · DEC-036
Co-sign
CFO + CHRO
commit gate
EU AI Act
Annex III §4
high-risk · conformity pack at P2
1

Why REW exists

Compensation is the most legally-sensitive data a company holds and the most reputation-sensitive computation a company runs. When a payslip arrives wrong, the recipient never trusts the system again. When a parameter changes retroactively, the company has produced two contradictory truths about the same period — a phenomenon that auditors call a fraud signal and members call "you cheated me". REW exists to make these failure modes structurally impossible: append-only ledger, deterministic compute, dual sign-off, structural exclusion from BRAIN, and a P1 floor that even a buggy evaluation cannot violate.

📐
Deterministic compute

Payslips are pure functions of (parameters, timesheet, leave, bonus pool). Same inputs → same bytes. Forever. A 2024 payslip recomputed in 2030 produces the same PDF SHA-256.

🛡
P1 floor invariant

No evaluation, no performance review, no agent, no buggy code path can propose a cut to P1 in cash. The constraint is enforced at the DB layer with a CHECK + at the application layer with a policy gate.

🚫
Zero BRAIN leakage

DEC-036: compensation numbers never enter the BRAIN audit ledger. Audit rows reference an opaque_payslip_id; the body is in REW's encrypted keyspace, not in BRAIN. Even a full BRAIN export reveals no comp.

The bet (Bet 5 in the PRD) is that treating Total Rewards as a moat is itself the moat. Companies that get comp wrong lose people; companies that get comp verifiable and explainable earn trust that compounds. REW's invariants — append-only, deterministic, P1-protected, parameter-versioned — make the comp system itself a trust-producing artifact, not just a payroll engine.

2

What it does — 5W1H2C5M

A structured decomposition. Every cell traces back to PRD §9.14 and SRS §4.14.

AxisQuestionAnswer
5W · WhatWhat is REW?An append-only compensation ledger + deterministic payroll compute + BP (Bonus Points) ledger with anti-inflation interest. Encrypted PDF payslip output with cryptographic SHA-256 integrity. Read-only narrator surface (payslip_explain) for the CUO/CFO-skill agent.
5W · WhoWho is touched?Members: every employee gets a monthly payslip. Owners: HR/Ops Lead initiates close; CFO + CHRO co-sign commit; CEO approves final publication. Forbidden: agents never write to REW; agents read only the payslip_explain narrative.
5W · WhenWhen does REW act?(a) Monthly close cycle (D-3 to D+2 around month-end); (b) per-grant bonus award (Founder approval gate); (c) anti-retroactive replay job at every parameter change (CI); (d) annual SI/PIT remittance prep; (e) Member termination → final-pay compute.
5W · WhereWhere does it run?P1: single region (Singapore SG-1) backed by AWS RDS Postgres with REW-specific KMS key (separate from HR's CCCD key, separate from BRAIN's signing key). PDFs at rest with retention lock = 10 years.
5W · WhyWhy a separate, isolated module?Because comp data leaking into BRAIN is the worst privacy outcome possible. Because retroactive parameter changes are an audit-failure / fraud signal. Because P1-cut bugs are existential to trust.
1H · HowHow does it work?(1) Parameter table append-only, every row carries effective_from + effective_to + superseded_by + version_hash. (2) Compute kernel is a pure function with a serde-stable input snapshot. (3) PDF generation is deterministic (LaTeX with frozen fonts, fixed timestamp metadata). (4) PDF SHA-256 stored alongside row; integrity verifiable forever. (5) Co-sign predicate at AUTH (CFO + CHRO scopes both required for commit).
2C · CostCost budget?P1: ~$30/month (RDS schema + Fargate task + S3 with object-lock). 50-tenant: ~$100/month. Per-payslip cost: ~$0.01 amortised (LaTeX rendering dominates).
2C · ConstraintsConstraints?(a) P1 invariant — sev-0 if violated. (b) Anti-retroactive — sev-0 if violated. (c) BRAIN exclusion (DEC-036) — CI gate. (d) Vietnamese SI/PIT line-items per Decree 152/2020 + Circular 111/2013. (e) 10-year retention. (f) EU AI Act high-risk — conformity pack at P2.
5M · MaterialsStack?Rust 1.81 · axum 0.7 · sqlx · PostgreSQL 16 · LaTeX (tectonic) for deterministic PDF · ring for SHA-256 · serde for canonical-JSON input snapshots · AWS KMS for per-payslip encryption · S3 with object-lock for archival.
5M · MethodsMethod choices?Append-only with supersession (no UPDATE). Pure-function compute kernel with property tests for determinism. Tectonic for deterministic LaTeX. Co-sign predicate at AUTH gateway. CI replay job that recomputes last 24 months on every parameter change.
5M · MachinesDeployment?Fargate task in SG-1 (P1). Multi-AZ Postgres RDS. S3 retention lock = 10 years. SG HoldCo branch: SGD payroll mode (P2 stretch).
5M · ManpowerWho maintains?HR/Ops Lead (R for operations) + CEO (A for sign-off) + CFO (R for commit co-sign) + CHRO (R for co-sign, P3+ seat).
5M · MeasurementHow measured?(FR pending)..010 (PRD §9.14). KPIs: close-cycle completion days, recompute-determinism CI pass rate, BRAIN-leak incident count, P1-cut-attempt blocked count.
3

Architecture

REW is an isolated service with four surfaces (REST admin for the close cycle, GraphQL read-mostly for the Member payslip portal, MCP narrator-only tools for agents, internal gRPC for HR roster sync), three stores (Postgres with REW-specific KMS key for ledger rows, S3 with object-lock for PDFs, KMS for column-level encryption), and a deliberately constrained audit path that emits opaque event references to BRAIN — never numbers.

graph TB subgraph CLIENTS ["Clients"] HR["HR/Ops (SPA)"] CFO["CFO co-sign UX"] CHRO["CHRO co-sign UX"] MEMBER["Member portal
(own payslip only)"] CUO["🤖 CUO/CFO-skill
narrator · read-only"] end subgraph EDGE ["Edge"] AR["Apollo Router
JWT + RBAC + co-sign predicate"] end subgraph REW ["REW service (Rust · axum)"] GQL["GraphQL subgraph
read-mostly"] REST["REST admin
close · commit · publish"] KERNEL["compute_kernel.rs
pure deterministic fn"] PARAM["parameters.rs
append-only versioned"] BP["bp_ledger.rs
BP unit-of-account + interest"] PDF["pdf_renderer.rs
tectonic deterministic"] NARR["narrator.rs
payslip_explain (read-only)"] COSIGN["cosign_guard.rs
CFO + CHRO predicate"] REPLAY["replay_check.rs
determinism CI"] end subgraph STORES ["Stores (isolated)"] PG[("PostgreSQL
compensation_change · payslip
parameters · bp_ledger
REW-specific KMS key")] S3[("AWS S3
payslip PDFs · object-lock 10y
REW-specific KMS")] KMS[("AWS KMS
rew-comp-key
distinct from HR + BRAIN")] end subgraph BOUNDARIES ["Compliance boundaries"] BRAIN["🧠 BRAIN
opaque event refs ONLY
(no comp numbers)"] OBS["👁 OBS
timing only
(no comp in traces)"] HRMOD["👥 HR
Member roster (read)"] AUTH["🔐 AUTH
co-sign predicate"] end HR --> AR CFO --> AR CHRO --> AR MEMBER --> AR CUO --> AR AR --> GQL AR --> REST AR --> NARR REST --> COSIGN COSIGN --> AUTH REST --> KERNEL KERNEL --> PARAM KERNEL --> BP KERNEL --> HRMOD KERNEL --> PDF PDF --> S3 REST --> PG GQL --> PG BP --> PG PARAM --> PG PG --> KMS S3 --> KMS REST -.opaque ref.-> BRAIN REW --> OBS REPLAY --> KERNEL classDef planned fill:#fef6e0,stroke:#92400e classDef store fill:#f5f3ff,stroke:#7c3aed classDef boundary fill:#fee2e2,stroke:#dc2626 classDef extern fill:#f5ede6,stroke:#45210e class GQL,REST,KERNEL,PARAM,BP,PDF,NARR,COSIGN,REPLAY planned class PG,S3,KMS store class BRAIN,OBS boundary class HRMOD,AUTH extern

Internal components

ComponentPath (planned)Responsibility
compute_kernel.rsservices/rew/src/compute_kernel.rsPure deterministic function. Input: (parameters_version, member_snapshot, timesheet, leave, bp_balance). Output: (P1, P2, P3, SI, PIT, net). No I/O. No clock. No randomness.
parameters.rsservices/rew/src/parameters.rsAppend-only parameter store. Every row carries effective_from + effective_to + superseded_by + version_hash. Rejects UPDATE at DB layer.
bp_ledger.rsservices/rew/src/bp_ledger.rsBP (Bonus Points) ledger. Append-only credits + debits + monthly interest accrual at ACB savings rate (versioned parameter).
payslip.rsservices/rew/src/payslip.rsPayslip row writer. Calls kernel, persists computed values + parameter version hash + SHA-256 of PDF.
pdf_renderer.rsservices/rew/src/pdf_renderer.rsDeterministic PDF via tectonic. Frozen fonts (Inter, Vietnamese Pro), fixed timestamp metadata, no creator field, no PRODUCER drift.
cosign_guard.rsservices/rew/src/cosign_guard.rsPredicate check at commit boundary: requires both rew.commit_co_sign:cfo and rew.commit_co_sign:chro within 5-minute window. Single-signer commits rejected.
narrator.rsservices/rew/src/narrator.rsRead-only MCP surface for the CUO/CFO-skill: explains a payslip in prose. Never proposes changes. Never writes.
anomaly_surface.rsservices/rew/src/anomaly_surface.rsSurfaces deltas vs prior month — flags ±20% swings for HR review during close. Narrative-only output.
replay_check.rsservices/rew/src/replay_check.rsCI replay job. On every parameter change, recomputes last 24 months' payslips; asserts byte-identical SHA-256.
p1_guard.rsservices/rew/src/p1_guard.rsP1-protection invariant enforcer. Rejects any compensation_change row that would result in a smaller P1 cash value than the prior period.
si_pit.rsservices/rew/src/si_pit.rsVietnamese SI (BHXH + BHYT + BHTN) and PIT line-item computation per Decree 152/2020 + Circular 111/2013. Versioned along with other parameters.
sg_branch.rsservices/rew/src/sg_branch.rsSGD payroll branch for Singapore HoldCo. Activated only when tenant's data_residency = "sg-1" and member's jurisdiction = "SG". (P2 stretch.)
brain_bridge.rsservices/rew/src/brain_bridge.rsWrites opaque event refs to BRAIN (e.g. rew.payslip.published:opaque_id_01HZJ…). Never writes comp numbers. CI gate inspects emitted-row JSON for blocklist keys.
migrations/services/rew/migrations/sqlx migrations. Append-only constraints (no DELETE / UPDATE on ledger tables). Separate KMS key from HR + BRAIN.
4

Data model

The schema is built around append-only with supersession. There is no UPDATE on a published row; there is a new row that supersedes the old one. Parameters, compensation changes, BP ledger entries, and published payslips all follow this discipline. The DB role used by the application has no DELETE or UPDATE grant on these tables, only INSERT.

erDiagram TENANT ||--o{ POSITION : "defines" TENANT ||--o{ PARAMETER_VERSION : "publishes" POSITION ||--o{ LEVEL : "has" MEMBER ||--o{ COMPENSATION_CHANGE : "history of" MEMBER ||--o{ PAYSLIP : "receives" MEMBER ||--|| BP_BALANCE : "current view" MEMBER ||--o{ BP_LEDGER_ENTRY : "credits/debits" PAYSLIP }o--|| PARAMETER_VERSION : "computed against" COMPENSATION_CHANGE }o--|| PARAMETER_VERSION : "subject to" BONUS_POOL ||--o{ POOL_DISTRIBUTION : "splits into" POOL_DISTRIBUTION ||--o{ PAYSLIP : "feeds P3" POSITION { uuid id PK uuid tenant_id FK string code "engineer-l2 | designer-l3 | …" string display_name string family "engineering | design | ops | biz" } LEVEL { uuid id PK uuid position_id FK string code "L1 | L2 | L3 | …" int rank } PARAMETER_VERSION { uuid id PK uuid tenant_id FK string name "p1-base-schedule | p2-allowance-schedule | bp-interest-rate | si-rates-vn" string version "2026.04" bytea version_hash "SHA-256 of canonical JSON" jsonb payload "frozen at publish" timestamp effective_from timestamp effective_to "NULL = current" uuid superseded_by FK "NULL if current" uuid published_by FK timestamp published_at } COMPENSATION_CHANGE { uuid id PK uuid member_id FK decimal p1_base "MUST be ≥ prior p1_base (P1 invariant)" decimal p2_allowance string level_code uuid parameter_version_id FK string reason "hire | promotion | annual_review | role_change" uuid approved_by FK uuid co_signed_by FK timestamp effective_from timestamp effective_to uuid superseded_by FK } PAYSLIP { uuid id PK uuid member_id FK string period "2026-04" decimal p1 decimal p2 decimal p3 decimal si_employee decimal pit decimal net uuid parameter_version_id FK bytea input_snapshot_hash "canonical JSON of all inputs" bytea pdf_sha256 string pdf_s3_uri "KMS-wrapped" string status "draft | reviewed | committed | published" timestamp published_at } BP_LEDGER_ENTRY { uuid id PK uuid member_id FK string kind "credit | debit | interest" decimal amount_bp string reason uuid parameter_version_id FK timestamp recorded_at } BP_BALANCE { uuid member_id PK decimal current_balance_bp timestamp last_interest_at } BONUS_POOL { uuid id PK uuid tenant_id FK string period "2026" decimal pool_size decimal allocated string status "open | locked" } POOL_DISTRIBUTION { uuid id PK uuid bonus_pool_id FK uuid member_id FK decimal share decimal performance_factor "0.0 to 1.5" decimal amount timestamp distributed_at } MEMBER { uuid id PK uuid tenant_id FK string jurisdiction "VN | SG" } TENANT { uuid id PK string data_residency }

3P income structure — schedule example

ComponentWhat it isSource of valueVariabilityTax treatment (VN)
P1 BaseContractual base salary in cash, paid monthly. Floor invariant — never reduced by evaluation.Position × Level schedule (parameter)Only raised; never loweredPIT progressive; SI bases on capped portion (Decree 152)
P2 AllowanceCash allowance — tied to role tier (e.g. mentorship allowance for L3+, leadership allowance for managers). Can move up or down with tier changes.Position-tier schedule (parameter)Tier-up = raise; tier-down (rare) = adjustPIT progressive; SI excluded for designated allowance kinds
P3 PerformanceCash overflow from the annual bonus pool, distributed via POOL_DISTRIBUTION with a performance factor.BP fund × Voting Power × performance factorVariable; can be 0 in any periodPIT progressive at the time of payout
BP (Bonus Points)Unit-of-account ledger, monthly interest at ACB savings rate. Members can convert BP → cash (P3) at specified windows.Awarded via founder approval; accumulates interestBP balance grows over time even idlePIT due on conversion to cash, not on accrual
5

API surface

Three surfaces. GraphQL read-mostly for the Member payslip portal (with strict self-scope). REST admin for the close cycle, with the CFO + CHRO co-sign predicate. MCP narrator-only tools for the CUO/CFO-skill — no write tools, no parameter change tools, no commit tools.

GraphQL subgraph (read-mostly · self-scope)

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

type Payslip @key(fields: "id") {
  id: ID!
  memberId: ID!
  period: String!
  p1: Money!
  p2: Money!
  p3: Money!
  siEmployee: Money!
  pit: Money!
  net: Money!
  parameterVersionId: ID!
  pdfSha256: String!
  pdfUrl: String!  # pre-signed S3, 60s TTL
  status: PayslipStatus!
  publishedAt: DateTime
}

type Money {
  amount: String!  # string to avoid float drift
  currency: String!  # VND | SGD
}

type BpBalance {
  memberId: ID!
  currentBalanceBp: String!
  lastInterestAt: DateTime!
}

enum PayslipStatus { DRAFT REVIEWED COMMITTED PUBLISHED }

type Query {
  myPayslips(since: Date): [Payslip!]!  # only own payslips
  payslip(id: ID!): Payslip
    @requiresScopes(scopes: [["rew.payslip_read"]])
  myBpBalance: BpBalance!
}

# NO mutations on GraphQL. All writes go through REST admin
# with the cosign_guard.

REST admin surface (planned · co-sign required)

MethodPathPurposeCo-sign?
POST/admin/cyclesOpen a monthly close cycle.HR/Ops
POST/admin/cycles/{period}/draftCompute draft payslips (kernel, no commit).HR/Ops
GET/admin/cycles/{period}/anomaliesSurface ±20% deltas vs prior month.readonly
POST/admin/cycles/{period}/commitCommit cycle: locks payslip rows.CFO + CHRO
POST/admin/cycles/{period}/publishPublish payslips: emit opaque BRAIN refs + notify Members.CEO (final)
POST/admin/parametersPublish a new parameter version (e.g. annual review).CFO + CHRO + CEO
POST/admin/compensation/{member_id}/changeAppend a compensation change (hire, promotion, annual review). P1-guard checked.CFO + CHRO
POST/admin/bonus-pool/{year}Allocate the annual bonus pool.CEO + CFO
POST/admin/bp/awardAward BP to a Member. Founder approval gate.Founder
POST/admin/bp/convertConvert BP → P3 cash (member-initiated, windowed).Member self
POST/admin/replay-checkRun the 24-month replay; CI hook.internal · CI
POST/admin/dsar/{member_id}/exportDSAR comp bundle (own only; managers blocked).DPO

MCP tool catalogue (narrator-only · no write tools)

Tool nameInputsOutputsAnnotations
cyberos.rew.payslip_explainpayslip_idnarrative text (no numbers in raw response — uses opaque tokens like "your P1 component")readonly · scope=rew.narrator
cyberos.rew.anomalies_summaryperiodnarrative deltasreadonly · for HR/Ops during close
cyberos.rew.bp_balance_explainmember_id (own only)narrative BP growth explanationreadonly · self-scope
cyberos.rew.policy_lookuppolicy_topicquoted Total Rewards Appendix paragraphreadonly · scope=rew.policy_read

Forbidden: no cyberos.rew.compute_payslip, no cyberos.rew.commit_cycle, no cyberos.rew.change_compensation. Compute is owned by HR/Ops via the REST admin path with co-sign. Agents narrate; humans decide.

6

Key flows

Flow 1 — Monthly close cycle (input → compute → review → commit → publish)

sequenceDiagram autonumber participant HR as HR/Ops (SPA) participant R as REW REST /admin/cycles participant K as compute_kernel.rs participant HRM as 👥 HR (roster + leave) participant T as ⏱ TIME (timesheet) participant CUO as 🤖 CUO/CFO-skill participant CFO as CFO participant CHRO as CHRO participant CEO as CEO participant S3 as AWS S3 (object-lock) participant B as 🧠 BRAIN (opaque ref only) HR->>R: POST /admin/cycles {period:"2026-04"} R->>R: open cycle status="open" HR->>R: POST /admin/cycles/2026-04/draft R->>HRM: read roster + leave snapshot R->>T: read timesheet snapshot R->>K: compute(parameters_v, members, timesheet, leave, bp) K-->>R: payslip rows (draft) R->>CUO: anomalies_summary (read-only narrative) CUO-->>HR: "3 members have ±20% delta vs Mar; flagged" HR->>HR: investigate + adjust if needed R->>R: status="reviewed" HR->>R: POST /admin/cycles/2026-04/commit R->>CFO: request co-sign R->>CHRO: request co-sign CFO-->>R: WebAuthn assertion (cosign:cfo) CHRO-->>R: WebAuthn assertion (cosign:chro) R->>R: cosign_guard ✓ (both within 5min window) R->>R: lock payslip rows + status="committed" HR->>R: POST /admin/cycles/2026-04/publish R->>CEO: request final approval CEO-->>R: approve R->>K: render PDFs (deterministic tectonic) R->>S3: archive PDFs (KMS, object-lock 10y) R->>R: payslip.status="published", record pdf_sha256 R->>B: opaque ref "rew.payslip.published:" Note over R,B: BRAIN row contains NO comp numbers,
just an opaque pointer.

CFO + CHRO assertions must both arrive within 5 minutes; otherwise cosign_guard resets and both must re-submit. This prevents accidental long-pending half-signed commits.

Flow 2 — Anti-retroactive parameter change (with replay check)

sequenceDiagram autonumber participant CEO as CEO participant CFO as CFO participant CHRO as CHRO participant R as REW /admin/parameters participant K as compute_kernel.rs participant RPC as replay_check.rs (CI) participant B as 🧠 BRAIN CEO->>R: POST /admin/parameters
{name:"p1-base-schedule", version:"2026.05", payload:…} R->>R: 3-way co-sign (CEO + CFO + CHRO) R->>R: INSERT parameter_version row
(prior version effective_to = now) R->>RPC: trigger replay of last 24 months RPC->>K: replay april-2024 with parameters effective at april-2024-end K-->>RPC: SHA-256 of payslip PDF RPC->>RPC: compare with stored sha alt all 24 months identical RPC-->>R: ✓ determinism preserved R->>R: parameter_version.status = "published" R->>B: opaque ref "rew.params.published:2026.05" else any drift RPC-->>R: ✗ FAIL — determinism broken R->>R: ROLLBACK parameter change R->>B: opaque ref "rew.params.rejected:replay_drift" Note over R,B: New parameters NEVER affect old periods.
If replay drifts, parameters are rejected. end

This is the anti-retroactive invariant in action: publishing a new parameter version is only allowed if recomputing the last 24 months against the historical effective parameters still yields byte-identical PDFs. If the kernel itself changed in a way that breaks determinism, the change is rejected.

Flow 3 — Promotion → compensation change (P1-guard in action)

sequenceDiagram autonumber participant L as 📈 LEARN (promotion outcome) participant HR as HR/Ops participant R as REW /admin/compensation/{member}/change participant P1G as p1_guard.rs participant CFO as CFO participant CHRO as CHRO participant B as 🧠 BRAIN L-->>HR: promotion outcome "L2 → L3 for mai@…" HR->>R: POST /admin/compensation//change
{level:"L3", p1_base:, reason:"promotion"} R->>P1G: check new_p1 ≥ prior_p1 ? alt p1 raised (or equal) P1G-->>R: ✓ P1-invariant preserved R->>CFO: request co-sign R->>CHRO: request co-sign CFO-->>R: WebAuthn (cosign:cfo) CHRO-->>R: WebAuthn (cosign:chro) R->>R: INSERT compensation_change row R->>B: opaque ref "rew.comp.changed:" else p1 reduced — REJECT P1G-->>R: ✗ sev-0 P1 cut attempted R-->>HR: 422 "P1 protection invariant" R->>B: opaque ref "rew.p1_cut_attempted:blocked" Note over R,B: A bug — or a malicious actor — cannot reduce P1 in cash;
only a multi-party amendment to the Total Rewards Appendix could. end

Flow 4 — BP fund allocation + P3 distribution

sequenceDiagram autonumber participant CEO as CEO participant CFO as CFO participant R as REW /admin/bonus-pool/2026 participant K as compute_kernel.rs participant L as 📈 LEARN (VP roll-up) participant M as Member portal participant B as 🧠 BRAIN CEO->>R: POST /admin/bonus-pool/2026
{pool_size: VND} R->>R: co-sign (CEO + CFO) R->>L: read VP per Member L-->>R: VP map R->>K: allocate(pool, VP, performance_factor) K-->>R: pool_distribution rows R->>R: INSERT pool_distribution R->>R: per-Member: append P3 to current period payslip R->>B: opaque ref "rew.pool.distributed:2026" Note over M: at next published payslip,
Member sees P3 line item with narrative explanation.

Flow 5 — Payslip narrator (read-only · CUO/CFO-skill)

sequenceDiagram autonumber participant U as Member (asks CUO) participant CUO as 🤖 CUO router participant NARR as REW narrator.rs participant PG as REW DB (read-only) U->>CUO: "explain my April payslip" CUO->>NARR: cyberos.rew.payslip_explain {payslip_id} NARR->>PG: read payslip + parameter_version (self-scope) PG-->>NARR: payslip + params NARR->>NARR: synthesise prose narrative
(refers to "P1 component" "P2 component" — not numeric) NARR-->>CUO: narrative text CUO-->>U: "Your April payslip reflects the P1 schedule for L2 engineer,
plus a P2 allowance for mentorship, plus a P3 distribution
from the 2026 bonus pool of 0.4× pool share. See your portal
for the numeric breakdown." Note over NARR,CUO: numeric values stay in REW's keyspace;
only the Member portal renders them to the Member directly.
7

Close-cycle lifecycle

A monthly close cycle traverses five states. Each transition writes an opaque audit row (never a number) to BRAIN.

stateDiagram-v2 [*] --> Open: HR/Ops opens cycle for period Open --> Drafted: kernel runs · payslips draft rows Drafted --> Reviewed: anomalies surfaced · HR investigates · adjusts inputs Reviewed --> Committed: CFO + CHRO co-sign within 5min Reviewed --> Drafted: re-draft after input adjustment Committed --> Published: CEO approves · PDFs rendered · S3 archived Published --> [*] Committed --> Reversed: extraordinary correction · new cycle opened Reversed --> [*]

Cycle calendar (default · configurable)

DayActivityOwner
D-3 (month-end - 3)Open cycle. Timesheet freeze warning to Members.HR/Ops
D-1Timesheet hard freeze. Leave reconciliation.HR/Ops
D (month-end)Draft compute. Anomaly surface to HR. CUO/CFO-skill narrative.HR/Ops + Agent (read-only)
D+1HR adjustments. Anomaly resolution.HR/Ops
D+2Commit: CFO + CHRO co-sign. CEO approves publish.CFO · CHRO · CEO
D+3Publish: PDFs render → S3 → Member notified.REW (auto)
D+5 (VN)BHXH remittance schedule (P3 stretch).HR/Ops
8

Functional Requirements

The CyberOS FR catalogue is being rebuilt one feature at a time via the open fr-author Agent Skill.

Previous FR enumerations were archived 2026-05-14 and are no longer reflected on this page. PRD/SRS narrative remains authoritative for the spec; specific FRs land here as they are re-authored.

9

Non-Functional Requirements

PRD §11.2.3 (security) and §11.2.5 (usability / explainability) bind on REW. Cross-referenced at nfr-catalog.html#rew.

NFR IDConcernTargetMeasurement
N(FR pending)Comp number in BRAIN ledger row= 0 — sev-0CI: brain_bridge emit JSON inspected against blocklist of keys + numeric value patterns
N(FR pending)P1 reduction attempts blocked= 100% (zero leak)p1_guard property test; chaos test injects p1 cut and asserts rejection
N(FR pending)Single-signer commit attempts blocked= 100%cosign_guard integration test
N(FR pending)KMS-key isolation (REW key distinct from HR + BRAIN)3 distinct key handlesKMS policy inspection; cross-key access blocked
N(FR pending)Determinism — same inputs → same PDF SHA-256100% (24-month replay)replay_check.rs CI on every parameter change
N(FR pending)Append-only at DB layer (no UPDATE / DELETE grant on ledger tables)enforcedDB role inspection · CI gate on migrations
N(FR pending)Cycle draft compute p95 (50 members)≤ 8 sbench/cycle.rs
N(FR pending)PDF render p95 (per payslip)≤ 600 msbench/pdf.rs
N(FR pending)Cycle-day availability≥ 99.9% during D-3..D+5SLO monitor
N(FR pending)Payslip durability (10-year retention)0 lost PDFsS3 object-lock + quarterly inventory
N(FR pending)Payslip explainability (EU AI Act Art. 14)narrator covers all line itemspolicy review + member usability test
N(FR pending)Member dispute path SLO≤ 5 working days to CEO adjudicationdispute queue dashboard
N(FR pending)EU AI Act Annex III §4 conformity at P2full conformity pack signed by DPO + CLOP2 release gate
10

Dependencies

REW is deliberately constrained. It reads from HR (roster + leave) and TIME (timesheet). It writes opaque references to BRAIN — never numbers. Agents read the narrator surface only.

graph LR subgraph upstream ["REW depends on"] AUTH["🔐 AUTH
JWT + co-sign predicate"] HRMOD["👥 HR
roster + leave (read)"] TIME["⏱ TIME
timesheet (read)"] LEARN["📈 LEARN
VP for P3 distribution"] KMS["🔑 AWS KMS
rew-comp-key (distinct)"] S3["🗂 AWS S3
PDFs · object-lock 10y"] BRAIN["🧠 BRAIN
opaque refs only"] end REW["💎 REW"] subgraph downstream ["REW is read by"] CUO["🤖 CUO/CFO-skill
narrator only"] MEM["Member portal
self-payslip only"] INV["🧾 INV
(not used; INV is AR side)"] DPO["DPO
DSAR exports"] end AUTH --> REW HRMOD --> REW TIME --> REW LEARN --> REW KMS --> REW S3 --> REW REW -.opaque ref.-> BRAIN REW --> CUO REW --> MEM REW --> DPO classDef planned fill:#fef6e0,stroke:#92400e classDef shipped fill:#f5ede6,stroke:#45210e classDef forbidden fill:#fee2e2,stroke:#dc2626 class REW planned class AUTH,HRMOD,TIME,LEARN,CUO,MEM,DPO planned class BRAIN,KMS,S3 shipped class INV forbidden
11

Compliance scope

REW is the EU AI Act Annex III §4 high-risk module (employment-decision automation). It has to defend against Vietnamese labour-law audits, PDPL DSAR requests, and EU AI Act conformity assessments simultaneously.

Regulation / standardArticle / clauseREW feature that satisfies it
EU AI Act (Reg. 2024/1689)Annex III §4 — Employment & worker managementREW is the high-risk system. P2 conformity pack: risk management, data governance, technical docs, transparency, human oversight ((FR pending)), accuracy/robustness ((FR pending) determinism).
EU AI ActArt. 14 — Human oversightMember can dispute → CEO adjudicates within 5 working days; CEO can override any automated computation.
EU AI ActArt. 13 — Transparencycyberos.rew.payslip_explain narrator; user-facing PDF includes parameter version + computation explanation.
Vietnam Labour Code (2019)Art. 90 — Wage / salaryP1 floor is the contractual base; P1-guard invariant enforces.
Vietnam Labour CodeArt. 96 — Pay periodMonthly cycle by default; per-tenant override (weekly / bi-weekly) supported.
Decree 152/2020/NĐ-CPArt. 5 — SI contribution ratesBHXH 8%/17.5%, BHYT 1.5%/3%, BHTN 1%/1% encoded as versioned parameter si-rates-vn.
Circular 111/2013/TT-BTCArt. 7 — Personal income taxPIT progressive schedule encoded as versioned parameter pit-schedule-vn.
VN Tax Law10-year retentionS3 object-lock 10-year + DB row append-only.
Vietnam PDPL (Law 91/2025)Art. 14 — DSARMember-self DSAR ((FR pending)); managers structurally blocked from cross-member comp views.
Vietnam PDPLArt. 7 — Sensitive dataComp classified restricted; separate KMS; access requires rew.payslip_read scope.
GDPR (EU 2016/679)Art. 22 — Automated individual decision-makingEU AI Act conformity pack + Art. 14 human override ((FR pending)).
GDPRArt. 32 — Security of processingKMS-wrapped at rest · co-sign at commit · append-only ledger.
ISO/IEC 27001:2022A.5.13 — Information labellingComp fields classified; cross-module exfiltration blocked at gateway.
SOC 2 Type IICC6.1, CC8.1RBAC + co-sign + audit chain + deterministic replay.
12

Risk entries

REW's risks are largely about integrity (determinism, append-only) and privacy (BRAIN leakage). The P1-cut and BRAIN-leak risks are both rated catastrophic.

IDRiskLikelihoodImpactOwnerMitigation
R-REW-001Comp number leaks into BRAIN audit rowLowCatastrophicCSObrain_bridge.rs emit JSON inspected by CI gate against numeric blocklist; integration test asserts opaque ref pattern only.
R-REW-002P1 cut proposed by buggy evaluationLowCatastrophic (legal)CEOp1_guard at app layer + DB CHECK constraint; property test attempts P1 cut and asserts rejection.
R-REW-003Retroactive parameter change breaks old payslip recomputationMediumHighCTOreplay_check.rs CI on every parameter change; rejects publish if any of last 24 months drifts.
R-REW-004Single-signer commit slips throughLowHighCFOcosign_guard with 5-min window; both signatures required; integration test asserts blockage.
R-REW-005Deterministic PDF render breaks (font/timestamp drift)MediumHighCTOTectonic with pinned font versions; PDF metadata stripped to {producer:none, creation_date:fixed}; CI byte-identical assertion.
R-REW-006Cross-tenant comp leakage via manager scopeLowCatastrophicCSOManager role has NO rew.payslip_read scope; can only see HR data; DSAR queries reject if subject ≠ self.
R-REW-007BP interest accrual drift (compounding bug)MediumMediumCFOBP interest is a deterministic function of (period, rate version); replay_check covers BP too.
R-REW-008EU AI Act conformity gap discovered at auditMediumHighCLO + DPOP2 conformity pack drafted at design time; gap analysis annually; legal-counsel sign-off.
R-REW-009Agent attempts compute via narrator surface (excessive agency)LowMediumCSOMCP catalogue has ZERO write tools; narrator is read-only; CI gate verifies tool catalogue surface.
R-REW-01010-year retention violated by S3 lifecycle bugLowHighCTOObject-lock governance mode; lifecycle policy review at every deploy; quarterly inventory audit.
13

KPIs

REW health rolls up into 10 KPIs across throughput, integrity, and compliance.

KPIFormulaSourceTarget
Close-cycle completion (days)published_at - cycle.opened_atREW DB≤ 5 working days
Determinism replay pass ratereplay_check pass / runsCI= 100%
P1-cut attempts blockedp1_guard rejections / periodOBStracked; alert on any > 0 in prod
Single-signer commit attempts blockedcosign_guard rejectionsOBStracked; alert on prod attempts
Comp-in-BRAIN incidentsCI gate failuresCI= 0
Member disputes resolved (5 working days)disputes resolved within SLO / totalREW DB≥ 95%
PDF render p95histogramOBS≤ 600 ms
Anomaly false-positive rateflagged but unchanged / flaggedREW DB≤ 30%
BP interest precision (drift)computed - expected (basis points)property test= 0 bps
EU AI Act conformity scoreconformity items passed / totalP2 audit= 100% at P2 release
14

RACI matrix

REW is operationally owned by HR/Ops Lead; legally accountable to the CEO; compute-co-signed by CFO + CHRO. DPO owns DSAR; CLO owns EU AI Act conformity.

ActivityCEOHR/OpsCFOCHROCSODPOCLO
Monthly close cycleARRRIII
Compensation change (hire/promo)CRRRIII
Parameter version publishARRRCCC
Bonus pool allocationA/RIRCIII
BP award (founder approval)A/RRCCIII
Member dispute adjudicationA/RRRRICC
EU AI Act conformity packCIICCRA
DSAR fulfilment (comp scope)ICIICA/RC
Determinism CI gate maintenanceIIIIA/RII

R Responsible · A Accountable · C Consulted · I Informed.

15

Planned CLI surface

Admin CLI cyberos-rew for HR/Ops. Destructive commands print numeric output only on stdout, never to logs.

1. Open a close cycle

$ cyberos-rew cycle open --period 2026-04

[cycle opened]
  period:   2026-04
  status:   open
  freeze:   2026-04-28 23:59:59 (timesheet hard freeze)
[audit]    brain seq=15001 (opaque ref only)

2. Draft compute

$ cyberos-rew cycle draft --period 2026-04

[draft]    computing payslips for 12 members…
[kernel]   pure function · 0 I/O · 0 randomness
[anomaly]  2 members flagged (±20% delta vs March):
             mai@…   (P3 spike — bonus pool distribution)
             linh@… (P1 raise — promotion L1→L2)
[status]   drafted
[audit]    brain seq=15002 (opaque)

3. Commit (CFO + CHRO co-sign)

$ cyberos-rew cycle commit --period 2026-04 \
    --cosign-cfo --cosign-chro

[cosign]  cfo: hoa@cyberskill.com (WebAuthn) ✓
[cosign]  chro: thanh@cyberskill.com (WebAuthn) ✓
[guard]   cosign_guard: both signatures within 5min window ✓
[commit]  12 payslip rows locked
[status]  committed
[audit]   brain seq=15011 (opaque)

4. Publish

$ cyberos-rew cycle publish --period 2026-04 --ceo-approve

[ceo]     stephen@cyberskill.com (WebAuthn) ✓
[render]  12 PDFs via tectonic (deterministic)
[render]  all SHA-256 stable vs draft
[s3]      archived to s3://rew/payslips//2026-04.pdf (object-lock 10y)
[notify]  12 members notified (CHAT + email)
[status]  published
[audit]   brain seq=15021 (opaque "rew.payslip.published" × 12)

5. Publish a new parameter version

$ cyberos-rew parameters publish \
    --name p1-base-schedule \
    --version 2026.05 \
    --payload p1-2026.05.json \
    --cosign-ceo --cosign-cfo --cosign-chro

[3-way cosign]   ceo ✓  cfo ✓  chro ✓
[replay-check]   replaying last 24 months against historical params…
[replay-check]   apr-2024 ✓  may-2024 ✓  …  mar-2026 ✓
[replay-check]   all 24 months: SHA-256 byte-identical ✓
[publish]        p1-base-schedule v2026.05 published
[supersede]      prior version v2026.04 effective_to = now
[audit]          brain seq=15045 (opaque "rew.params.published:2026.05")

6. Award BP

$ cyberos-rew bp award \
    --member hoa@cyberskill.com \
    --amount 500 \
    --reason "Q1 contribution to ESOP migration" \
    --founder-approve

[founder] stephen@cyberskill.com (WebAuthn) ✓
[bp]      +500 BP awarded to hoa@cyberskill.com
[balance] new balance: 2,840 BP (interest 2.5%/yr at ACB rate)
[audit]   brain seq=15052 (opaque "rew.bp.awarded")

7. DSAR comp export (member-self)

$ cyberos-rew dsar-export --self --output mycomp.zip

[dsar]   subject:    mai@cyberskill.com (self)
[dsar]   payslips:   24 (last 2 years)
[dsar]   parameters: 12 versions referenced
[dsar]   bp ledger:  47 entries
[dsar]   compensation_changes: 3
[dsar]   written:    mycomp.zip (3.4 MB, KMS-encrypted)
[audit]  brain seq=15061 (opaque "rew.dsar.exported")
16

Phase status & estimates

Status
Planned
P1 design phase
Est. LoC (Rust)
~6,800
services/rew + sqlx migrations
Planned tests
140+
incl. determinism replay suite
External libs
~12
axum · sqlx · tectonic · ring · serde · aws-sdk-kms
CLI subcommands
~22 planned
cyberos-rew entrypoint
P1 budget
~$30/mo
RDS schema + Fargate + S3 obj-lock
CapabilityStatus
3P income compute kernel (deterministic)planned · P1
Append-only parameter store + supersessionplanned · P1
P1-protection invariant (p1_guard)planned · P1
CFO + CHRO co-sign predicateplanned · P1
Monthly close cycle UXplanned · P1
Anomaly surface (±20% delta)planned · P1
Deterministic PDF render (tectonic)planned · P1
24-month replay CI gateplanned · P1
BP ledger + ACB interest accrualplanned · P1
Payslip narrator MCP (read-only)planned · P1
Vietnamese SI/PIT line-itemsplanned · P1
Member self-DSAR comp exportplanned · P1
BP → P3 conversion windowsplanned · P2
Singapore HoldCo SGD branchplanned · P2
EU AI Act Annex III §4 conformity packplanned · P2
BHXH remittance integrationplanned · P3
Member-dispute → CEO adjudication flowplanned · P2
17

References

  • PRD §9.14 — REW module FRs ((FR pending) through (FR pending)).
  • PRD §19.14 — REW architecture posture, Bet 5 framing.
  • PRD Bet 5 — "The Total Rewards Appendix is a moat too" (DEC-036 BRAIN exclusion).
  • PRD §11.2.3 — Security NFRs (SEC-002: zero P1 reduction).
  • SRS §4.14 — Formal (FR pending) through (FR pending) with verification methods.
  • Total Rewards & Career Path Appendix — Legal source of truth; 3P decomposition; P1 protection.
  • EU AI Act (Reg. 2024/1689) — Annex III §4 employment-decision automation high-risk classification; Art. 13 transparency; Art. 14 human oversight.
  • GDPR (EU 2016/679) — Art. 22 automated decision-making safeguards.
  • Vietnam Labour Code (2019) — Art. 90 wage, Art. 96 pay period.
  • Decree 152/2020/NĐ-CP — SI contribution rates and base computation.
  • Circular 111/2013/TT-BTC — Personal income tax progressive schedule.
  • Vietnam PDPL (Law 91/2025) — Art. 7 sensitive data; Art. 14 DSAR.
  • ISO/IEC 27001:2022 — A.5.13 information labelling; A.5.16 identity management.
  • Architecture context: services.html#rew.