TorbatYar/docs/reference/policy-engine-contracts.md

Policy Engine Contracts

Contracts only. No policy evaluation engine in this wave.
Targets: policy-targets.md
Contract version: policy-engine.v1
ADR: ADR-023 (v1.2)

---

1. Purpose

Policies are independent commercial/governance rules that may constrain eligibility, licensing, pricing application, activation, visibility, quotas, marketplace behavior, compliance, and related concerns.

Policies are not products, bundles, assets, or capabilities. They attach by reference.

---

2. PolicyDefinition

Field	Type	Meaning
registry_object_id	uuid	Universal ID
policy_code	string	Stable open code
policy_kind	string	Open kind — see §3
display_name	string
status	enum	draft | active | deprecated | retired
version_code	string
priority	int	Higher wins on conflict (future engine)
effect	enum	allow | deny | require | transform | inform
targets[]	PolicyTargetBinding	See policy-targets.md
conditions	object	Open predicate bag (unevaluated here)
parameters	object	Open parameters
metadata_ref	uuid?
documentation_ref	string?
ext	object

---

3. Policy kinds (examples — open registry)

policy_kind	Meaning
eligibility	Who may acquire/activate
licensing	License grant constraints
commercial	General commercial rules
regional	Country/region gates
pricing	Which pricing items apply
tax	Tax class / inclusivity hints
promotion	Promotional windows
discount	Discount class application
activation	Activation pipeline constraints
feature_visibility	UI/API surface visibility
capability_access	Capability enable rules
quota	Quota ceilings
marketplace_rules	Marketplace listing/commerce rules
compliance	Regulatory/compliance
security	Security posture rules
support	Support tier rules
trial	Trial eligibility/duration
renewal	Renewal behavior
expiration	Expiry / sunset

Unlimited future policy_kind values MAY be registered without architecture changes.

---

4. Policy evaluation (future — documented only)

Logical interface (not implemented):

EvaluatePolicies(context) → { decisions[], deny_reasons[], transforms[] }

Context MAY include tenant, workspace, product, bundle, subscription, license, region, industry, asset, metadata snapshots.

---

5. Invariants

1. Policies never write foreign service databases directly — they inform Core commercial / activation decisions.
2. Payment L2/L3 remain owned by Payment; policies may gate L1 or commercial packaging only.
3. Tax/discount/promotion engines are not authorized by these contracts alone.
4. No ownership transfer to Marketplace or Experience via policy kinds.