README

Tenancy primitives for Flametrench: organizations, memberships, and invitations. Spec-conformant revoke-and-re-add lifecycle, atomic invitation acceptance, sole-owner protection, and a mem_/tup_ duality maintained without drift.

The PHP counterpart of @flametrench/tenancy — same shapes, same invariants, same operations. Both SDKs are exercised against the spec's conformance suite so applications can move between the two languages with no behavioral surprises.

Status: v0.2.0 (stable). PHP 8.3+ required. Includes the production-ready PostgresTenancyStore alongside the in-memory reference store; the Postgres adapter mirrors in-memory semantics byte-for-byte at the SDK boundary, and per ADR 0013 cooperates with adopter-side outer transactions via savepoints when nested.

Install

composer require flametrench/tenancy

Quick start

use Flametrench\Tenancy\InMemoryTenancyStore;
use Flametrench\Tenancy\PreTuple;
use Flametrench\Tenancy\Role;

$store = new InMemoryTenancyStore();

// Alice creates Acme and becomes its owner.
['org' => $org, 'ownerMembership' => $owner] = $store->createOrg('usr_0190...alice');

// Alice invites Carol with a project-scoped grant.
$inv = $store->createInvitation(
    orgId: $org->id,
    identifier: 'carol@example.com',
    role: Role::Guest,
    invitedBy: 'usr_0190...alice',
    expiresAt: new DateTimeImmutable('+7 days'),
    preTuples: [new PreTuple('viewer', 'proj', '0190...project42')],
);

// Carol accepts. Membership and pre-tuples materialize atomically.
$result = $store->acceptInvitation($inv->id, asUsrId: 'usr_0190...carol');

API

TenancyStore defines the contract every backend implements. Both the in-memory reference implementation and the production-ready PostgresTenancyStore ship with this package.

Spec conformance

Mirrors the normative spec: see spec/docs/tenancy.md and the design decisions in ADR 0002 + ADR 0003.

The 31 PEST tests in this package cover every sole-owner-protection path, the replaces chain on role changes, atomic invitation acceptance with pre-tuple materialization, admin-hierarchy enforcement, ownership transfer atomicity, and removedBy attribution.

Errors

Every error is a Flametrench\Tenancy\Exceptions\TenancyException subclass with a stable flametrenchCode matching the OpenAPI Error envelope:

Development

composer install
composer test

License

Apache License 2.0. Copyright 2026 NDC Digital, LLC.