Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
354e3da
feat: PPT-526 add Partner->Client hierarchy and client ownership columns
camreeves Aug 18, 2026
5c20249
feat: PPT-526 Stage 3 add cross-tenant authorization grants table
camreeves Aug 19, 2026
b4d8110
refactor: PPT-526 rename Client to Organization
camreeves Aug 19, 2026
6f1f5cb
refactor: PPT-526 spell Organisation and renumber the tenancy migrati…
camreeves Oct 7, 2026
735ebed
feat: PPT-526 partner staff organisations, organisation-scoped names …
camreeves Oct 7, 2026
1848a3d
fix: PPT-526 keep the last-admin guard cluster-wide
camreeves Oct 7, 2026
9ceba03
chore: PPT-526 renumber the tenancy migrations above master
stakach Nov 5, 2026
9714744
style: PPT-526 short block notation in zone spec
stakach Nov 5, 2026
928f6af
feat: PPT-526 record change history for partners, organisations and g…
stakach Nov 5, 2026
58c1789
fix(spec): unique signage AI provider names in the generator
stakach Nov 5, 2026
b502009
fix(shard.yml): require pg-orm 2.5.3
stakach Nov 5, 2026
5adba67
Merge remote-tracking branch 'origin/master' into PPT-526-partner-client
stakach Nov 16, 2026
adf6640
test: quarantine ambiguous ownership during upgrades
stakach Nov 16, 2026
6625649
fix: quarantine unresolved organisation ownership
stakach Nov 16, 2026
35351e7
test: retain durable tenancy reconciliation records
stakach Nov 16, 2026
cd0ffdc
test: cover legacy name and domain migration safety
stakach Nov 16, 2026
833d1de
test: exclude generated columns from legacy authority fixture
stakach Nov 16, 2026
b3be732
feat: retain durable tenancy reconciliation records
stakach Nov 16, 2026
18d197a
fix: preserve global name validation until tenancy is enabled
stakach Nov 16, 2026
6b8db9f
test: isolate expected reconciliation uniqueness failures
stakach Nov 16, 2026
83eaa0f
fix: preserve ambiguous legacy authority domains
stakach Nov 16, 2026
363cf89
fix: recognise normalized quarantined authority domains
stakach Nov 16, 2026
3871fda
test: quarantine module ownership across edge boundaries
stakach Nov 16, 2026
716ca76
fix: quarantine module inference across edge ownership
stakach Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,33 @@ docker system prune --all
./test
```

## Organisation name validation

`PLACE_TENANCY_ENFORCE` defaults to false, preserving global name uniqueness for
zones, systems, edges and brokers. Enable it consistently across model consumers
to validate names within each organisation instead. Specs can override the shared
setting with `PlaceOS::Model::OrganisationScopedName.enforce = true` or `false`;
assign `nil` to restore the environment default.

After allowing duplicate names across organisations, resolve those duplicates
before disabling enforcement or rolling back to binaries with global validation.
Changing validation mode never renames existing records.

### Upgrading existing ownership

The additive ownership migrations retry only unassigned rows. Assigned ownership
is retained and suspicious references are exposed through
`tenancy_ownership_conflicts` for explicit reconciliation. Unowned brokers and
unscoped trigger definitions remain intentional platform resources.

Legacy duplicate authority domains are preserved. Their unique index is deferred
until duplicates are resolved; the report identifies `duplicate_domain` rows and
domains renamed by an older migration as `quarantined_domain`. Resolve these
before enabling tenancy enforcement. The guarded index SQL in
[`20261117100700000_guard_authority_domains.sql`](migration/db/migrations/20261117100700000_guard_authority_domains.sql)
can be reapplied after explicit resolution. Migrations never merge domains or
organisations automatically.

## Contributing

See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
1 change: 1 addition & 0 deletions docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ services:
- ${PWD}/shard.yml:/app/shard.yml.input
- ${PWD}/coverage:/app/coverage
- ${PWD}/.ameba.yml:/app/.ameba.yml
- ${PWD}/migration/db/migrations:/app/migration/db/migrations:ro
depends_on:
- migrator
- postgres
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,203 @@
-- +micrate Up
-- SQL in section 'Up' is executed when this migration is applied

-- MERGE-TIME CHECK: micrate refuses out-of-order version ids (see models#323).
-- If any later-dated migration lands on master before this merges, renumber
-- this file AND 20261105100600000 above it (preserving schema-before-backfill
-- order). Existing installations use additive migrations for corrections;
-- applied versions are not rerun.

-- ---------------------------------------------------------------------------
-- PPT-526: the Partner → Organisation → Authority(domain) hierarchy.
--
-- partners: integrators/resellers (e.g. NTT). `management = true` marks the
-- platform operator's own organisation (PlaceOS staff) — the "management
-- organisation" concept from the ticket, done at the partner level. `parent_id`
-- reserves a 2-tier channel (distributor → reseller) without any UI or
-- enforcement yet.
--
-- organisations: the customer organisation (e.g. UCLA, Acadian). `partner_id` NULL
-- means organisation-owned (self-managed, no integrator). `payer` records who is
-- invoiced: 'partner' (integrator pays us and re-bills, the default channel
-- model) or 'organisation' (direct). A organisation without a partner can only pay for
-- itself — enforced by CHECK.
--
-- Every delete path is RESTRICT: removing a partner/organisation must go through an
-- orchestrated teardown (the PPT-1203 pattern), never a silent DB cascade —
-- model-level cleanup callbacks do not fire on DB cascades.
-- ---------------------------------------------------------------------------
CREATE TABLE IF NOT EXISTS "partners"(
id UUID PRIMARY KEY DEFAULT uuidv7(),
name TEXT NOT NULL,
description TEXT NOT NULL DEFAULT '',
management BOOLEAN NOT NULL DEFAULT false,
parent_id UUID REFERENCES "partners"(id) ON DELETE RESTRICT,
config JSONB NOT NULL DEFAULT '{}',
created_at TIMESTAMPTZ NOT NULL,
updated_at TIMESTAMPTZ NOT NULL
);

CREATE UNIQUE INDEX IF NOT EXISTS partners_name_unique
ON "partners" USING BTREE (name);
CREATE INDEX IF NOT EXISTS partners_parent_id_index
ON "partners" USING BTREE (parent_id);

CREATE TABLE IF NOT EXISTS "organisations"(
id UUID PRIMARY KEY DEFAULT uuidv7(),
name TEXT NOT NULL,
description TEXT NOT NULL DEFAULT '',
partner_id UUID REFERENCES "partners"(id) ON DELETE RESTRICT,
payer TEXT NOT NULL DEFAULT 'partner'
CHECK (payer IN ('partner', 'organisation')),
config JSONB NOT NULL DEFAULT '{}',
created_at TIMESTAMPTZ NOT NULL,
updated_at TIMESTAMPTZ NOT NULL,
CONSTRAINT organisations_payer_requires_partner
CHECK (partner_id IS NOT NULL OR payer = 'organisation')
);

-- Organisation names are unique within a partner's book of business, and unique
-- among organisation-owned organisations. Two partial indexes because UNIQUE treats
-- NULLs as distinct — a plain UNIQUE (partner_id, name) would let every
-- organisation-owned organisation share a name.
CREATE UNIQUE INDEX IF NOT EXISTS organisations_name_unique_per_partner
ON "organisations" USING BTREE (partner_id, name) WHERE partner_id IS NOT NULL;
CREATE UNIQUE INDEX IF NOT EXISTS organisations_name_unique_owned
ON "organisations" USING BTREE (name) WHERE partner_id IS NULL;
CREATE INDEX IF NOT EXISTS organisations_partner_id_index
ON "organisations" USING BTREE (partner_id);

-- ---------------------------------------------------------------------------
-- Authority → Organisation ownership. Nullable at the DB level for backwards
-- compatibility (init seeds authorities before any organisation exists); the
-- provisioning flow and backfill populate it. RESTRICT so a organisation cannot be
-- deleted while it still owns domains.
-- ---------------------------------------------------------------------------
ALTER TABLE "authority"
ADD COLUMN IF NOT EXISTS organisation_id UUID;

ALTER TABLE ONLY "authority"
DROP CONSTRAINT IF EXISTS authority_organisation_id_fkey;
ALTER TABLE ONLY "authority"
ADD CONSTRAINT authority_organisation_id_fkey
FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT;

CREATE INDEX IF NOT EXISTS authority_organisation_id_index
ON "authority" USING BTREE (organisation_id);

-- Preserve existing domains. Ambiguous legacy rows remain available in flag-off
-- mode and are reported for explicit reconciliation before enforcement is enabled.
-- +micrate StatementBegin
DO $$
BEGIN
LOCK TABLE authority IN SHARE MODE;
IF EXISTS (SELECT domain FROM authority GROUP BY domain HAVING COUNT(*) > 1) THEN
RAISE NOTICE 'duplicate authority domains require explicit reconciliation; unique index deferred';
ELSE
CREATE UNIQUE INDEX IF NOT EXISTS authority_domain_unique ON authority USING BTREE (domain);
END IF;
END $$;
-- +micrate StatementEnd

-- ---------------------------------------------------------------------------
-- Organisation ownership columns on the (previously cluster-global) control plane.
-- Nullable: populated by the backfill migration where inference is
-- unambiguous, and by the provisioning flow for everything new. Query-path
-- enforcement is phased in separately (rest-api); these columns are the
-- ground truth it will filter on.
-- ---------------------------------------------------------------------------
ALTER TABLE "zone" ADD COLUMN IF NOT EXISTS organisation_id UUID;
ALTER TABLE "sys" ADD COLUMN IF NOT EXISTS organisation_id UUID;
ALTER TABLE "mod" ADD COLUMN IF NOT EXISTS organisation_id UUID;
ALTER TABLE "trigger" ADD COLUMN IF NOT EXISTS organisation_id UUID;
ALTER TABLE "edge" ADD COLUMN IF NOT EXISTS organisation_id UUID;
ALTER TABLE "broker" ADD COLUMN IF NOT EXISTS organisation_id UUID;

ALTER TABLE ONLY "zone"
DROP CONSTRAINT IF EXISTS zone_organisation_id_fkey;
ALTER TABLE ONLY "zone"
ADD CONSTRAINT zone_organisation_id_fkey
FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT;
ALTER TABLE ONLY "sys"
DROP CONSTRAINT IF EXISTS sys_organisation_id_fkey;
ALTER TABLE ONLY "sys"
ADD CONSTRAINT sys_organisation_id_fkey
FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT;
ALTER TABLE ONLY "mod"
DROP CONSTRAINT IF EXISTS mod_organisation_id_fkey;
ALTER TABLE ONLY "mod"
ADD CONSTRAINT mod_organisation_id_fkey
FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT;
ALTER TABLE ONLY "trigger"
DROP CONSTRAINT IF EXISTS trigger_organisation_id_fkey;
ALTER TABLE ONLY "trigger"
ADD CONSTRAINT trigger_organisation_id_fkey
FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT;
ALTER TABLE ONLY "edge"
DROP CONSTRAINT IF EXISTS edge_organisation_id_fkey;
ALTER TABLE ONLY "edge"
ADD CONSTRAINT edge_organisation_id_fkey
FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT;
ALTER TABLE ONLY "broker"
DROP CONSTRAINT IF EXISTS broker_organisation_id_fkey;
ALTER TABLE ONLY "broker"
ADD CONSTRAINT broker_organisation_id_fkey
FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT;

CREATE INDEX IF NOT EXISTS zone_organisation_id_index ON "zone" USING BTREE (organisation_id);
CREATE INDEX IF NOT EXISTS sys_organisation_id_index ON "sys" USING BTREE (organisation_id);
CREATE INDEX IF NOT EXISTS mod_organisation_id_index ON "mod" USING BTREE (organisation_id);
CREATE INDEX IF NOT EXISTS trigger_organisation_id_index ON "trigger" USING BTREE (organisation_id);
CREATE INDEX IF NOT EXISTS edge_organisation_id_index ON "edge" USING BTREE (organisation_id);
CREATE INDEX IF NOT EXISTS broker_organisation_id_index ON "broker" USING BTREE (organisation_id);

-- Per-organisation name uniqueness for the estate. Dormant while organisation_id is NULL
-- (UNIQUE treats NULLs as distinct) and strictly weaker than the current
-- model-level global uniqueness, so it cannot conflict with existing data.
-- When query enforcement lands, the model-level checks flip from global to
-- organisation-scoped and these indexes become the hard guarantee.
CREATE UNIQUE INDEX IF NOT EXISTS zone_organisation_id_name_unique
ON "zone" USING BTREE (organisation_id, name) WHERE organisation_id IS NOT NULL;
CREATE UNIQUE INDEX IF NOT EXISTS sys_organisation_id_name_unique
ON "sys" USING BTREE (organisation_id, name) WHERE organisation_id IS NOT NULL;
CREATE UNIQUE INDEX IF NOT EXISTS edge_organisation_id_name_unique
ON "edge" USING BTREE (organisation_id, name) WHERE organisation_id IS NOT NULL;
CREATE UNIQUE INDEX IF NOT EXISTS broker_organisation_id_name_unique
ON "broker" USING BTREE (organisation_id, name) WHERE organisation_id IS NOT NULL;

-- +micrate Down
-- SQL section 'Down' is executed when this migration is rolled back

DROP INDEX IF EXISTS broker_organisation_id_name_unique;
DROP INDEX IF EXISTS edge_organisation_id_name_unique;
DROP INDEX IF EXISTS sys_organisation_id_name_unique;
DROP INDEX IF EXISTS zone_organisation_id_name_unique;

DROP INDEX IF EXISTS broker_organisation_id_index;
DROP INDEX IF EXISTS edge_organisation_id_index;
DROP INDEX IF EXISTS trigger_organisation_id_index;
DROP INDEX IF EXISTS mod_organisation_id_index;
DROP INDEX IF EXISTS sys_organisation_id_index;
DROP INDEX IF EXISTS zone_organisation_id_index;

ALTER TABLE ONLY "broker" DROP CONSTRAINT IF EXISTS broker_organisation_id_fkey;
ALTER TABLE ONLY "edge" DROP CONSTRAINT IF EXISTS edge_organisation_id_fkey;
ALTER TABLE ONLY "trigger" DROP CONSTRAINT IF EXISTS trigger_organisation_id_fkey;
ALTER TABLE ONLY "mod" DROP CONSTRAINT IF EXISTS mod_organisation_id_fkey;
ALTER TABLE ONLY "sys" DROP CONSTRAINT IF EXISTS sys_organisation_id_fkey;
ALTER TABLE ONLY "zone" DROP CONSTRAINT IF EXISTS zone_organisation_id_fkey;

ALTER TABLE "broker" DROP COLUMN IF EXISTS organisation_id;
ALTER TABLE "edge" DROP COLUMN IF EXISTS organisation_id;
ALTER TABLE "trigger" DROP COLUMN IF EXISTS organisation_id;
ALTER TABLE "mod" DROP COLUMN IF EXISTS organisation_id;
ALTER TABLE "sys" DROP COLUMN IF EXISTS organisation_id;
ALTER TABLE "zone" DROP COLUMN IF EXISTS organisation_id;

DROP INDEX IF EXISTS authority_domain_unique;
DROP INDEX IF EXISTS authority_organisation_id_index;
ALTER TABLE ONLY "authority" DROP CONSTRAINT IF EXISTS authority_organisation_id_fkey;
ALTER TABLE "authority" DROP COLUMN IF EXISTS organisation_id;

DROP TABLE IF EXISTS "organisations";
DROP TABLE IF EXISTS "partners";
Loading
Loading