@happyvertical/smrt-users 0.57.2 → 0.57.4

package/README.md

@@ -1336,10 +1336,68 @@ TenantService supports three modes: `flexible` (no auto-create), `personal` (aut
 | `Group` | Team within a tenant. Gains permissions via GroupRole. |
 | `Membership` | User + Tenant + Role junction. UNIQUE(userId, tenantId). |
 | `MembershipOverride` | Per-user permission grant/deny on a membership. |
+| `LegalMember` | Tenant-scoped legal member register entry, separate from authentication/RBAC membership and subscriptions. |
+| `MemberClass` | Configurable legal member classification; classes have no built-in authority or entitlement effect. |
+| `LegalMemberStatusHistory` | Append-only effective status history for historical and record-date queries. |
+| `LegalMemberReference` | Qualified reference to authoritative shares, dues, subscription, agreement, or ledger evidence; it never stores a balance. |
+| `MemberOfficerAppointment` | Effective-dated board/officer register entry; it is not an RBAC grant or ballot engine. |
 | `TenantPermissionOverride` | Tenant-level permission override (INHERIT/GRANT/DENY). |
 | `GroupMember`, `GroupRole`, `RolePermission` | Junction tables for groups and role-permission assignments. |
 | `AccessRequest` | "Request access / waitlist" record captured before a `User` exists. Closed generated surface — all access via `AccessRequestService`. |
 
+## Legal member register
+
+`MemberRegisterService` manages a tenant's legal member register. It is distinct
+from `Membership`, which is a user-to-tenant authorization row, and from
+subscriptions, which resolve paid entitlements. A legal member may be an
+individual or organisation and may link to a user/profile or an external-party
+reference, without requiring any of them.
+
+The service writes effective status history, references financial evidence
+without copying balances, and effective board/officer terms. `asOf(recordDate,
+policy)` produces persisted, neutral eligibility snapshots plus CSV/JSON
+exports. A policy that requires shares or dues evidence fails closed unless the
+register has an explicitly authoritative reference for every required kind; the
+snapshot names that missing evidence rather than inferring payment status.
+
+An omitted `memberClassKeys` policy allows every class; an explicit empty list
+allows none. `statuses` defaults to `['active']`, and an empty status list also
+allows none. Snapshots preserve normalized class keys (`null` means unrestricted),
+statuses, and required evidence kinds so the decision retains its policy inputs.
+
+Hosts must authorize the trusted `MemberRegisterActor` before constructing the
+service. Generated REST, CLI and MCP operations are closed for these sensitive
+records. Every service lookup and write stays in the actor's tenant; an active
+context for another tenant is rejected. Direct collections are trusted internal
+APIs, not an authorization boundary for untrusted input.
+
+`enroll`, `setStatus` and `asOf` require database transaction support and commit
+all of their writes together. History and references are append-only, and
+snapshots reject updates and deletes. Same-day history corrections use persisted
+sequence order. Eligibility uses effective history; `LegalMember.status` and
+`leftOn` are display caches refreshed by `setStatus`, so scheduled changes may
+make those caches stale until another write. Use `asOf` for record-date decisions.
+
+Use `revokeReference(referenceId, { effectiveOn })` when previously authoritative
+evidence is withdrawn. It appends a dated record targeting the original reference;
+that original stops supporting eligibility on the revocation date. Earlier dates
+and already saved snapshots remain unchanged. A replacement authoritative reference
+must be explicitly added when evidence becomes valid again.
+
+Enrollment accepts global profiles or profiles owned by the actor's tenant, and
+rejects foreign-tenant profiles. Members returned from enrollment and status changes
+are rebound to the caller's database so subsequent saves do not reuse a completed
+transaction's connection. Saves still require the appropriate tenant context.
+
+Apply the generated s-m-r-t manifest migration before using the register; its six
+new tables require no auth-membership or subscription backfill. `userId` links
+to the local `User`; `profileId` uses the cross-package reference
+`@happyvertical/smrt-profiles:Profile`. Financial evidence is an opaque
+`sourceType`/`sourceId` reference (for example
+`@happyvertical/smrt-ledgers:JournalEntry` or
+`@happyvertical/smrt-subscriptions:TenantSubscription`); the host validates its
+authority and effective dates, and no posting or balance is copied here.
+
 ### Collections
 
 | Export | Description |