From a1bc8e5cfa13414907edbc995e8f01a14240717e Mon Sep 17 00:00:00 2001
From: Dawson Toth <dawson@harperdb.io>
Date: Sun, 11 Oct 2026 04:16:46 -0400
Subject: [PATCH 1/7] feat(roles): edit a role's permissions in a visual
 editor, with JSON as the fallback

Add and Edit Role now open on a visual editor: role type, structure user
(none / all databases / selected databases), the existing operations
allowlist editor, a per-database table grid for read/insert/update/delete,
and per-table attribute scoping. "Edit as JSON" switches to the Monaco view
of the same draft, and the visual view comes back only while the JSON holds
a document it can represent; otherwise the JSON view lists why.

The JSON text stays the single source of truth. Every visual edit is a
copy-on-write patch of the keys it touches, so content the GUI does not
model is carried through unchanged and listed as kept. The editor no longer
seeds the JSON from calculateDefaultPermissions: its global Pick Attributes
flag rewrote every table's attribute list at once, and expanding a list
wrote the primary key as an explicit false row, which revokes the key Harper
otherwise derives from the other attributes.

Add Role creates the role with its full permission in one step, through
preparePermissionForSave. That also fixes creating a super user role: the
old form always sent structure_user beside super_user, which Harper's
validateNoSUPerms rejects. preparePermissionForSave now drops structure_user
beside super_user/cluster_user for the same reason.

Refs #1634

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 DESIGN.md                                     |   2 +
 src/features/instance/config/roles/DESIGN.md  |  49 ++
 .../config/roles/defaultCalculator.test.ts    |  94 ---
 .../config/roles/defaultCalculator.ts         | 166 -----
 .../roles/editor/RolePermissionEditor.tsx     | 185 +++++
 .../roles/editor/RoleVisualEditor.test.tsx    | 148 ++++
 .../config/roles/editor/RoleVisualEditor.tsx  | 700 ++++++++++++++++++
 .../roles/editor/rolePermissionModel.test.ts  | 333 +++++++++
 .../roles/editor/rolePermissionModel.ts       | 629 ++++++++++++++++
 .../roles/editor/useRolePermissionDraft.ts    |  32 +
 src/features/instance/config/roles/index.tsx  |  10 +-
 .../config/roles/modals/AddRoleModal.test.tsx |  99 +++
 .../config/roles/modals/AddRoleModal.tsx      | 138 ++--
 .../roles/modals/EditRoleModal.test.tsx       | 343 ++++++---
 .../config/roles/modals/EditRoleModal.tsx     | 279 ++-----
 .../roles/preparePermissionForSave.test.ts    |   9 +
 .../config/roles/preparePermissionForSave.ts  |  15 +-
 src/integrations/api/instance/auth/addRole.ts |  18 +-
 .../api/instance/auth/addRoleFormSchema.ts    |   2 -
 19 files changed, 2566 insertions(+), 685 deletions(-)
 create mode 100644 src/features/instance/config/roles/DESIGN.md
 delete mode 100644 src/features/instance/config/roles/defaultCalculator.test.ts
 delete mode 100644 src/features/instance/config/roles/defaultCalculator.ts
 create mode 100644 src/features/instance/config/roles/editor/RolePermissionEditor.tsx
 create mode 100644 src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx
 create mode 100644 src/features/instance/config/roles/editor/RoleVisualEditor.tsx
 create mode 100644 src/features/instance/config/roles/editor/rolePermissionModel.test.ts
 create mode 100644 src/features/instance/config/roles/editor/rolePermissionModel.ts
 create mode 100644 src/features/instance/config/roles/editor/useRolePermissionDraft.ts
 create mode 100644 src/features/instance/config/roles/modals/AddRoleModal.test.tsx

diff --git a/DESIGN.md b/DESIGN.md
index 3bc9a4b1f..728ea85f1 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -12,6 +12,8 @@ This file collects architecture and design notes for studio that aren't otherwis
 
 - [`src/features/instance/databases/DESIGN.md`](src/features/instance/databases/DESIGN.md) — when the browse grid may show its spinner, and why a table without a primary key can't be listed.
 
+- [`src/features/instance/config/roles/DESIGN.md`](src/features/instance/config/roles/DESIGN.md) — why the role editor's JSON text is the only source of truth, what forces the JSON view, and what Save changes on purpose.
+
 - [`docs/status-redesign.md`](docs/status-redesign.md) — port of analytics-viz visualizations + spec system into the instance Status tab. Covers: 7-tab IA, the data-path adapter (no SQL — `get_analytics` only), bucket-by-window clamps, chart-surface CSS tokens, feature-flag rollback, testing strategy. Read before touching `src/features/instance/status/**`.
 
 ## API explorer (the instance/cluster "APIs" tab)
diff --git a/src/features/instance/config/roles/DESIGN.md b/src/features/instance/config/roles/DESIGN.md
new file mode 100644
index 000000000..1ed6863af
--- /dev/null
+++ b/src/features/instance/config/roles/DESIGN.md
@@ -0,0 +1,49 @@
+# Instance roles — design notes
+
+## The role editor's JSON text is the only source of truth
+
+Both role modals edit a draft whose text is the role's `permission` JSON
+([`useRolePermissionDraft`](editor/useRolePermissionDraft.ts)). The visual editor
+([`RoleVisualEditor`](editor/RoleVisualEditor.tsx)) is a lens over that text, not a model of its
+own. It reads the parsed document, and every edit is a copy-on-write patch from
+[`rolePermissionModel`](editor/rolePermissionModel.ts) that changes only the keys it touches. A key
+the GUI does not model therefore survives a round-trip without the GUI knowing it exists. Examples
+are a database record's `describe`, which Harper's permission translator honours, and an attribute
+entry's `delete`, which role validation tolerates.
+
+Never serialize the role from a schema-derived template or from a typed model. The editor used to
+seed its JSON from `calculateDefaultPermissions`, and that template rewrote what it did not model.
+Its global "Pick Attributes" flag expanded or emptied every table's attribute list at once. When it
+expanded one, it wrote the primary key as an explicit `false` row, and that revokes the key Harper
+otherwise derives from the other attributes. Tables the role doesn't mention are left out of the
+JSON. The GUI renders them as no access, which is how Harper reads an absent table, and creates an
+entry only when one is first granted.
+
+Two kinds of content the GUI does not render are handled differently:
+
+- `getVisualEditorBlockers` lists shapes the GUI could only render by guessing. Examples are a
+  non-boolean CRUD flag, a non-array `attribute_permissions`, and an unusable `operations` value.
+  While the list is non-empty, the JSON view stays in charge and shows the list. Most of these are
+  shapes Harper's role validation rejects anyway.
+- `getPreservedEntries` lists content that is well-formed but not shown, and the GUI carries it
+  through unchanged. Databases and tables missing from describe_all are listed separately. Harper
+  rejects a role that names them (`SCHEMA_NOT_FOUND` / `TABLE_NOT_FOUND`), so the GUI offers to
+  remove them, but it never removes them on its own. An attribute entry missing from describe_all is
+  only "not shown", because describe_all omits `@computed` attributes unless asked.
+
+Save is the one place that changes the document on purpose. `preparePermissionForSave` writes a
+`null` `attribute_permissions` as `[]` (HarperFast/harper#3143). It also removes what Harper refuses
+beside `super_user` / `cluster_user`, which is everything, `structure_user` included. For
+`structure_user: true` it removes the per-table permissions, which no longer apply. Switching a role
+type in the GUI keeps everything else in the draft until then, so switching back within a session
+loses nothing.
+
+A visual edit keeps the object it produced instead of re-parsing its own text. That keeps object
+identity for every untouched database and table, so the memoized `DatabaseSection` / `TableRows`
+re-render only what changed, which matters on a schema with hundreds of tables.
+
+The Harper semantics the editor shows are written down where they are encoded. The effective
+attribute access, including the derived primary key and timestamps being read-only, is in
+`getAttributeViews`. What `structure_user` grants is in `StructureUserSection`'s copy. Each was
+traced to Harper 5.3.1 source and checked against its `role_validation` / `permissionsTranslator`
+before it reached UI copy. Re-check those before changing the copy.
diff --git a/src/features/instance/config/roles/defaultCalculator.test.ts b/src/features/instance/config/roles/defaultCalculator.test.ts
deleted file mode 100644
index cc88b1c77..000000000
--- a/src/features/instance/config/roles/defaultCalculator.test.ts
+++ /dev/null
@@ -1,94 +0,0 @@
-import { calculateDefaultPermissions } from '@/features/instance/config/roles/defaultCalculator';
-import { InstanceDatabaseMap, LocalRolePermission } from '@/integrations/api/api.patch';
-import { orderPermissionKeys, withOperations } from '@/integrations/api/localRolePermission';
-import { describe, expect, it } from 'vitest';
-
-// JSON.parse, not an object literal: a literal `__proto__` key sets the prototype instead of
-// creating an own property, so the fixture itself has to come from parsed JSON.
-const databaseMap = (json: string) => JSON.parse(json) as InstanceDatabaseMap;
-const oneTable = '{"dog":{"attributes":[{"attribute":"id"}]}}';
-
-describe('calculateDefaultPermissions', () => {
-	it('keeps a database named __proto__ as an own, serializable key', () => {
-		// Plain assignment would hit the prototype setter: the database would vanish from the
-		// template and from JSON.stringify, so the role could never be granted it.
-		const result = calculateDefaultPermissions({
-			instanceDatabaseMap: databaseMap(`{"__proto__":{"dog":{"attributes":[{"attribute":"id"}]}}}`),
-			currentRolePermissions: {},
-			version: '5.2.2',
-			showAttributes: false,
-		});
-
-		expect(Object.hasOwn(result, '__proto__')).toBe(true);
-		// Read the own property explicitly: `parsed.__proto__` would resolve the prototype instead.
-		const serialized = JSON.parse(JSON.stringify(result)) as object;
-		const record = Object.getOwnPropertyDescriptor(serialized, '__proto__')?.value as
-			| { tables: Record<string, unknown> }
-			| undefined;
-		expect(record?.tables).toHaveProperty('dog');
-		// The round trip the editor actually performs must preserve it too.
-		const roundTripped = JSON.parse(JSON.stringify(withOperations(orderPermissionKeys(result), ['sql'])));
-		expect(Object.hasOwn(roundTripped, '__proto__')).toBe(true);
-	});
-
-	it('skips a database named like a reserved key when the instance reserves it', () => {
-		const map = databaseMap(`{"operations":{"dog":{"attributes":[{"attribute":"id"}]}}}`);
-		// 5.2 reserves `operations` for the allowlist, so writing the database there would clobber it.
-		expect(
-			calculateDefaultPermissions({
-				instanceDatabaseMap: map,
-				currentRolePermissions: { operations: ['sql'] },
-				version: '5.2.2',
-				showAttributes: false,
-			}).operations,
-		).toEqual(['sql']);
-
-		// Below the allowlist floor the same name is just a database, so it gets a permission record.
-		const legacy = calculateDefaultPermissions({
-			instanceDatabaseMap: map,
-			currentRolePermissions: {},
-			version: '4.7.3',
-			showAttributes: false,
-		}).operations as unknown as { tables: Record<string, unknown> };
-		expect(legacy.tables).toHaveProperty('dog');
-	});
-
-	it('preserves an existing allowlist while rebuilding table permissions', () => {
-		const permission: LocalRolePermission = { operations: ['read_only'] };
-		const result = calculateDefaultPermissions({
-			instanceDatabaseMap: databaseMap(`{"data":${oneTable}}`),
-			currentRolePermissions: permission,
-			version: '5.2.2',
-			showAttributes: false,
-		});
-		expect(result.operations).toEqual(['read_only']);
-		expect(result.data).toBeDefined();
-	});
-
-	it('writes an empty attribute_permissions array when attributes are not picked, never null', () => {
-		// HarperFast/harper#3143: a stored `null` makes every `['*']` read the role sends 500.
-		const fresh = calculateDefaultPermissions({
-			instanceDatabaseMap: databaseMap(`{"data":${oneTable}}`),
-			currentRolePermissions: { super_user: false, structure_user: false },
-			version: '5.3.1',
-			showAttributes: false,
-		});
-		expect(fresh.data).toEqual({
-			tables: { dog: { read: false, insert: false, update: false, delete: false, attribute_permissions: [] } },
-		});
-
-		const stored = calculateDefaultPermissions({
-			instanceDatabaseMap: databaseMap(`{"data":${oneTable}}`),
-			currentRolePermissions: {
-				data: {
-					tables: { dog: { read: true, insert: false, update: false, delete: false, attribute_permissions: null } },
-				},
-			},
-			version: '4.7.40',
-			showAttributes: false,
-		});
-		expect(stored.data).toEqual({
-			tables: { dog: { read: true, insert: false, update: false, delete: false, attribute_permissions: [] } },
-		});
-	});
-});
diff --git a/src/features/instance/config/roles/defaultCalculator.ts b/src/features/instance/config/roles/defaultCalculator.ts
deleted file mode 100644
index 8fa18950f..000000000
--- a/src/features/instance/config/roles/defaultCalculator.ts
+++ /dev/null
@@ -1,166 +0,0 @@
-import { supportsOperationsAllowlist } from '@/features/instance/config/roles/operations/operationsCatalog';
-import {
-	InstanceDatabaseMap,
-	LocalLegacyRolePermissionTable,
-	LocalRolePermission,
-	LocalRolePermissionTable,
-	LocalRoleSchemaRecord,
-} from '@/integrations/api/api.patch';
-import { getDatabasePermissionRecord, RESERVED_PERMISSION_KEYS } from '@/integrations/api/localRolePermission';
-import { keyBy } from '@/lib/keyBy';
-
-export function calculateDefaultPermissions({
-	instanceDatabaseMap,
-	currentRolePermissions,
-	version,
-	showAttributes,
-}: {
-	instanceDatabaseMap: InstanceDatabaseMap;
-	currentRolePermissions: LocalRolePermission;
-	version: string;
-	showAttributes: boolean;
-}): LocalRolePermission {
-	const permissionStructure: LocalRolePermission = {
-		...currentRolePermissions,
-	};
-	if (
-		currentRolePermissions.super_user || currentRolePermissions.structure_user || currentRolePermissions.cluster_user
-	) {
-		return currentRolePermissions;
-	}
-	const [major, minor, patch] = version.split('.').map(number => parseInt(number, 10));
-	const legacy = version !== '2.0.000' && major <= 2 && minor <= 1 && patch <= 2;
-
-	// Plain assignment of a `__proto__` key would hit the prototype setter rather than create an own
-	// property, so the database would vanish from the template. Harper permits the name, so define
-	// the property instead of dropping the database.
-	const setDatabase = (name: string, record: LocalRoleSchemaRecord) => {
-		Object.defineProperty(permissionStructure, name, {
-			value: record,
-			writable: true,
-			enumerable: true,
-			configurable: true,
-		});
-		return record;
-	};
-
-	const allowlistSupported = supportsOperationsAllowlist(version);
-
-	for (const databaseName in instanceDatabaseMap) {
-		if (RESERVED_PERMISSION_KEYS.has(databaseName) && (databaseName !== 'operations' || allowlistSupported)) {
-			// A database named like a reserved permission key cannot be expressed in role JSON —
-			// writing it here would clobber the reserved value (e.g. a 5.0+ operations allowlist).
-			// Pre-5.0 Harper has no reserved `operations`, so there a database by that name is real.
-			continue;
-		}
-		const databaseRecord = setDatabase(databaseName, { tables: {} });
-		const extantDatabasePermissions = currentRolePermissions
-			&& getDatabasePermissionRecord(currentRolePermissions, databaseName, allowlistSupported);
-		for (const tableName in instanceDatabaseMap[databaseName]) {
-			const thisTable = instanceDatabaseMap[databaseName][tableName];
-			const attributes = thisTable.attributes.map((a) => a.attribute).sort();
-			const extantTablePermissions = extantDatabasePermissions
-				&& extantDatabasePermissions.tables?.[tableName];
-			if (legacy) {
-				databaseRecord.tables[tableName] = buildLegacy(
-					extantTablePermissions as LocalLegacyRolePermissionTable,
-					attributes,
-					showAttributes,
-				);
-			} else {
-				databaseRecord.tables[tableName] = buildCurrent(
-					extantTablePermissions as LocalRolePermissionTable,
-					attributes,
-					showAttributes,
-				);
-			}
-		}
-	}
-
-	return permissionStructure;
-}
-
-function buildLegacy(
-	extantTablePermissions: LocalLegacyRolePermissionTable | undefined,
-	attributes: string[],
-	showAttributes: boolean,
-): LocalLegacyRolePermissionTable {
-	const attributeRestrictionsMap = extantTablePermissions
-		&& keyBy(extantTablePermissions.attribute_restrictions, 'attribute_name');
-	return {
-		read: extantTablePermissions ? extantTablePermissions.read : true,
-		insert: extantTablePermissions ? extantTablePermissions.insert : true,
-		update: extantTablePermissions ? extantTablePermissions.update : true,
-		delete: extantTablePermissions ? extantTablePermissions.delete : true,
-		attribute_restrictions: attributes
-			.filter(() => showAttributes)
-			.map((a) => {
-				const extantAttributePermissions = attributeRestrictionsMap?.[a];
-
-				return {
-					attribute_name: a,
-					read: extantAttributePermissions
-						? extantAttributePermissions.read
-						: extantTablePermissions
-						? extantTablePermissions.read
-						: true,
-					insert: extantAttributePermissions
-						? extantAttributePermissions.insert
-						: extantTablePermissions
-						? extantTablePermissions.insert
-						: true,
-					update: extantAttributePermissions
-						? extantAttributePermissions.update
-						: extantTablePermissions
-						? extantTablePermissions.update
-						: true,
-					delete: extantAttributePermissions
-						? extantAttributePermissions.delete
-						: extantTablePermissions
-						? extantTablePermissions.delete
-						: true,
-				};
-			}),
-	};
-}
-
-function buildCurrent(
-	extantTablePermissions: LocalRolePermissionTable | undefined,
-	attributes: string[],
-	showAttributes: boolean,
-): LocalRolePermissionTable {
-	const attributePermissionsMap = extantTablePermissions
-		&& keyBy(extantTablePermissions.attribute_permissions || [], 'attribute_name');
-	return {
-		read: extantTablePermissions ? extantTablePermissions.read : false,
-		insert: extantTablePermissions ? extantTablePermissions.insert : false,
-		update: extantTablePermissions ? extantTablePermissions.update : false,
-		delete: extantTablePermissions ? extantTablePermissions.delete : false,
-		attribute_permissions: showAttributes
-			? attributes
-				.map((a: string) => {
-					const extantAttributePermissions = attributePermissionsMap?.[a];
-
-					return {
-						attribute_name: a,
-						read: extantAttributePermissions
-							? extantAttributePermissions.read
-							: extantTablePermissions?.attribute_permissions?.length
-							? false
-							: extantTablePermissions?.read || false,
-						insert: extantAttributePermissions
-							? extantAttributePermissions.insert
-							: extantTablePermissions?.attribute_permissions?.length
-							? false
-							: extantTablePermissions?.insert || false,
-						update: extantAttributePermissions
-							? extantAttributePermissions.update
-							: extantTablePermissions?.attribute_permissions?.length
-							? false
-							: extantTablePermissions?.update || false,
-					};
-				})
-			// Not `null`, which Harper stores and then 500s on for every `['*']` read (HarperFast/harper#3143).
-			: [],
-	};
-}
diff --git a/src/features/instance/config/roles/editor/RolePermissionEditor.tsx b/src/features/instance/config/roles/editor/RolePermissionEditor.tsx
new file mode 100644
index 000000000..513802c22
--- /dev/null
+++ b/src/features/instance/config/roles/editor/RolePermissionEditor.tsx
@@ -0,0 +1,185 @@
+import { TextLoadingSkeleton } from '@/components/TextLoadingSkeleton';
+import { Button } from '@/components/ui/button';
+import { useInstanceClientIdParams } from '@/config/useInstanceClient';
+import { getVisualEditorBlockers } from '@/features/instance/config/roles/editor/rolePermissionModel';
+import { RoleVisualEditor } from '@/features/instance/config/roles/editor/RoleVisualEditor';
+import { RolePermissionDraft } from '@/features/instance/config/roles/editor/useRolePermissionDraft';
+import { supportsOperationsAllowlist } from '@/features/instance/config/roles/operations/operationsCatalog';
+import { OperationsValueNotice } from '@/features/instance/config/roles/operations/OperationsValueNotice';
+import { useMonacoTheme } from '@/hooks/useMonacoTheme';
+import { InstanceDatabaseMap, LocalRolePermission } from '@/integrations/api/api.patch';
+import { getDescribeAllQueryOptions } from '@/integrations/api/instance/database/getDescribeAll';
+import { getRegistrationInfoQueryOptions } from '@/integrations/api/instance/status/getRegistrationInfo';
+import { classifyOperationsValue } from '@/integrations/api/localRolePermission';
+import { Editor } from '@/lib/monaco/MonacoEditor';
+import { useQuery } from '@tanstack/react-query';
+import { CodeIcon, RefreshCwIcon, Table2Icon } from 'lucide-react';
+import { useDeferredValue, useMemo, useState } from 'react';
+
+export interface RoleEditorSchema {
+	instanceDatabaseMap?: InstanceDatabaseMap;
+	version?: string;
+	isLoading: boolean;
+	isError: boolean;
+	retry: () => void;
+}
+
+/** The instance schema and version both role modals render against. */
+export function useRoleEditorSchema(): RoleEditorSchema {
+	const instanceParams = useInstanceClientIdParams();
+	// Permission editing only needs the schema tree, never record counts, so this shares the
+	// count-free describe_all cache entry the Databases tab populates.
+	const describeAll = useQuery(getDescribeAllQueryOptions({ ...instanceParams, skipRecordCount: true }));
+	const registrationInfo = useQuery(getRegistrationInfoQueryOptions(instanceParams));
+	return {
+		instanceDatabaseMap: describeAll.data,
+		version: registrationInfo.data?.version,
+		isLoading: describeAll.isPending || registrationInfo.isPending,
+		// A failed background refetch of data already in hand is not a reason to lose the visual editor.
+		isError: (describeAll.isError && !describeAll.data) || (registrationInfo.isError && !registrationInfo.data),
+		retry: () => {
+			void describeAll.refetch();
+			void registrationInfo.refetch();
+		},
+	};
+}
+
+/**
+ * Saving past an unusable `operations` value would normalize it away and widen the role, so it has
+ * to be repaired in the JSON first. Without a version the allowlist floor is unknown, and Harper's
+ * own role validation is left to reject a malformed value.
+ */
+export function isOperationsValueUnusable(permission: LocalRolePermission | null, version: string | undefined) {
+	if (!permission || !version) {
+		return false;
+	}
+	const kind = classifyOperationsValue(permission, supportsOperationsAllowlist(version));
+	return kind === 'breaks-auth' || kind === 'malformed';
+}
+
+const MAX_LISTED_BLOCKERS = 5;
+
+/**
+ * Visual-first role permission editor with a JSON escape hatch (HarperFast/studio#1634), mirroring
+ * the schema editor's toggle. The draft's text is the single source of truth: the visual editor
+ * patches the parsed document and writes the result back, and the JSON view edits the text
+ * directly, so switching views never loses an edit. The visual view is offered only while the text
+ * holds a document it can represent; otherwise the JSON view says why and stays in charge.
+ */
+export function RolePermissionEditor({
+	draft,
+	schema,
+	readOnly,
+}: {
+	draft: RolePermissionDraft;
+	schema: RoleEditorSchema;
+	readOnly?: boolean;
+}) {
+	const { text, permission } = draft;
+	const monacoTheme = useMonacoTheme();
+	const { instanceDatabaseMap, version } = schema;
+	const schemaReady = !!instanceDatabaseMap && !!version;
+	// Undecided until the schema loads; then the view opens on the visual editor when it can.
+	const [preferJson, setPreferJson] = useState<boolean>();
+	// The JSON view re-checks on every keystroke; deferring keeps typing responsive on a large role.
+	const deferredPermission = useDeferredValue(permission);
+	const analysed = preferJson === true ? deferredPermission : permission;
+	const blockers = useMemo(() => {
+		if (!instanceDatabaseMap || !version) {
+			return [];
+		}
+		return analysed
+			? getVisualEditorBlockers(analysed, instanceDatabaseMap, version)
+			: ['The JSON is not a valid object.'];
+	}, [analysed, instanceDatabaseMap, version]);
+	const visualAvailable = schemaReady && !!analysed && blockers.length === 0;
+	if (preferJson === undefined && schemaReady) {
+		setPreferJson(!visualAvailable);
+	}
+
+	const operationsKind = permission && version
+		? classifyOperationsValue(permission, supportsOperationsAllowlist(version))
+		: 'absent';
+	const operations = permission?.operations;
+
+	if (schema.isLoading && !schema.isError) {
+		return <TextLoadingSkeleton />;
+	}
+
+	if (preferJson === false && visualAvailable && permission && instanceDatabaseMap && version) {
+		return (
+			<div className="flex min-h-0 flex-1 flex-col gap-2">
+				<div className="flex justify-end">
+					<Button type="button" variant="defaultOutline" size="sm" onClick={() => setPreferJson(true)}>
+						<CodeIcon /> Edit as JSON
+					</Button>
+				</div>
+				<div className="min-h-0 flex-1 overflow-y-auto pr-1">
+					<RoleVisualEditor
+						permission={permission}
+						onChange={draft.setPermission}
+						instanceDatabaseMap={instanceDatabaseMap}
+						version={version}
+						readOnly={readOnly}
+					/>
+				</div>
+			</div>
+		);
+	}
+
+	return (
+		<div className="flex min-h-0 flex-1 flex-col gap-2">
+			<div className="flex items-start justify-between gap-2">
+				<div className="text-xs text-muted-foreground">
+					{schema.isError
+						? (
+							<span className="flex items-center gap-2">
+								The visual editor needs this instance's schema and version, which didn't load.
+								<Button type="button" variant="defaultOutline" size="sm" onClick={schema.retry}>
+									<RefreshCwIcon /> Retry
+								</Button>
+							</span>
+						)
+						: blockers.length > 0 && (
+							<>
+								<p>The visual editor can't show this role until the JSON is fixed:</p>
+								<ul className="list-disc pl-4">
+									{blockers.slice(0, MAX_LISTED_BLOCKERS).map((blocker) => <li key={blocker}>{blocker}</li>)}
+									{blockers.length > MAX_LISTED_BLOCKERS && <li>…and {blockers.length - MAX_LISTED_BLOCKERS} more.</li>}
+								</ul>
+							</>
+						)}
+				</div>
+				{schemaReady && (
+					<Button
+						type="button"
+						variant="defaultOutline"
+						size="sm"
+						className="shrink-0"
+						disabled={!visualAvailable}
+						onClick={() => setPreferJson(false)}
+					>
+						<Table2Icon /> Visual editor
+					</Button>
+				)}
+			</div>
+			{(operationsKind === 'breaks-auth' || operationsKind === 'malformed') && (
+				<OperationsValueNotice
+					kind={operationsKind}
+					// Only a record implies a database of that name, which is the half the remedy has to mention.
+					databaseCollision={operations !== null && typeof operations === 'object' && !Array.isArray(operations)}
+				/>
+			)}
+			<div className="min-h-64 flex-1">
+				<Editor
+					className="h-full w-full"
+					theme={monacoTheme}
+					defaultLanguage="json"
+					value={text}
+					options={{ readOnly, automaticLayout: true }}
+					onChange={(value) => draft.setText(value ?? '')}
+				/>
+			</div>
+		</div>
+	);
+}
diff --git a/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx b/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx
new file mode 100644
index 000000000..5fc050c7f
--- /dev/null
+++ b/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx
@@ -0,0 +1,148 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { getTableEntry } from '@/features/instance/config/roles/editor/rolePermissionModel';
+import { RoleVisualEditor } from '@/features/instance/config/roles/editor/RoleVisualEditor';
+import { InstanceDatabaseMap, LocalRolePermission } from '@/integrations/api/api.patch';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { useState } from 'react';
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+
+const schema = {
+	data: {
+		dog: {
+			primary_key: 'id',
+			attributes: [{ attribute: 'id' }, { attribute: 'name' }, { attribute: '__createdtime__' }],
+		},
+		cat: { primary_key: 'id', attributes: [{ attribute: 'id' }] },
+	},
+	dev: { thing: { primary_key: 'id', attributes: [{ attribute: 'id' }] } },
+} as unknown as InstanceDatabaseMap;
+
+beforeAll(() => {
+	Element.prototype.hasPointerCapture ??= () => false;
+	Element.prototype.setPointerCapture ??= () => undefined;
+	Element.prototype.releasePointerCapture ??= () => undefined;
+	Element.prototype.scrollIntoView ??= () => undefined;
+	if (typeof window.PointerEvent === 'undefined') {
+		window.PointerEvent = class extends MouseEvent {} as typeof PointerEvent;
+	}
+});
+
+afterEach(cleanup);
+
+/** Holds the document like the modal does, and exposes the latest one to the test. */
+function renderEditor(initial: unknown, version = '5.3.1') {
+	const latest = { current: initial as LocalRolePermission };
+	function Harness() {
+		const [permission, setPermission] = useState(latest.current);
+		return (
+			<RoleVisualEditor
+				permission={permission}
+				onChange={(next) => {
+					latest.current = next;
+					setPermission(next);
+				}}
+				instanceDatabaseMap={schema}
+				version={version}
+			/>
+		);
+	}
+	render(<Harness />);
+	return latest;
+}
+
+const checkbox = (name: string) => screen.getByRole('checkbox', { name }) as HTMLInputElement;
+const table = (read: boolean, attributes: unknown = [], rest: object = {}) => ({
+	read,
+	insert: false,
+	update: false,
+	delete: false,
+	attribute_permissions: attributes,
+	...rest,
+});
+
+describe('RoleVisualEditor', () => {
+	it('shows a database-wide action as mixed and sets it on every table at once', () => {
+		const latest = renderEditor({ data: { tables: { dog: table(true) } } });
+
+		const allRead = checkbox('Read on every table in data');
+		expect(allRead.checked).toBe(false);
+		expect(allRead.indeterminate).toBe(true);
+		fireEvent.click(allRead);
+		expect(latest.current).toEqual({ data: { tables: { dog: table(true), cat: table(true) } } });
+		fireEvent.click(checkbox('Read on every table in data'));
+		expect(latest.current).toEqual({ data: { tables: { dog: table(false), cat: table(false) } } });
+	});
+
+	it("shows a scoped table's effective attribute access, including a derived primary key", () => {
+		renderEditor({
+			data: {
+				tables: {
+					dog: table(true, [
+						{ attribute_name: 'name', read: true, insert: false, update: false },
+						{ attribute_name: '__createdtime__', read: false, insert: true, update: true },
+					]),
+				},
+			},
+		});
+
+		fireEvent.click(screen.getByRole('button', { name: 'Attribute permissions for data.dog' }));
+		expect(checkbox('Read on data.dog.id').checked).toBe(true);
+		expect(screen.getByText(/isn't listed, so it gets whatever access any other attribute has/)).toBeTruthy();
+		// A timestamp only ever gets read; its stored insert does not show as granted.
+		expect(checkbox('Insert on data.dog.__createdtime__').checked).toBe(false);
+		expect(checkbox('Insert on data.dog.__createdtime__').disabled).toBe(true);
+		// The attributes-column summary counts attributes with any access.
+		expect(screen.getByRole('button', { name: 'Attribute permissions for data.dog' }).textContent).toContain('2 of 3');
+	});
+
+	it('grants the table action when an attribute is given it, and restores a list switched off and on', () => {
+		const latest = renderEditor({ data: { tables: { dog: table(true) } } });
+
+		fireEvent.click(screen.getByRole('button', { name: 'Attribute permissions for data.dog' }));
+		fireEvent.click(screen.getByRole('switch', { name: 'Limit data.dog to specific attributes' }));
+		fireEvent.click(checkbox('Update on data.dog.name'));
+		const dog = () => getTableEntry(latest.current, 'data', 'dog');
+		expect(dog()?.update).toBe(true);
+		const scoped = dog()?.attribute_permissions;
+
+		fireEvent.click(screen.getByRole('switch', { name: 'Limit data.dog to specific attributes' }));
+		expect(dog()?.attribute_permissions).toEqual([]);
+		fireEvent.click(screen.getByRole('switch', { name: 'Limit data.dog to specific attributes' }));
+		expect(dog()?.attribute_permissions).toEqual(scoped);
+	});
+
+	it('does not restore attribute grants the table no longer has', () => {
+		const latest = renderEditor({ data: { tables: { dog: table(true) } } });
+
+		fireEvent.click(screen.getByRole('button', { name: 'Attribute permissions for data.dog' }));
+		const limit = () => screen.getByRole('switch', { name: 'Limit data.dog to specific attributes' });
+		fireEvent.click(limit());
+		fireEvent.click(limit());
+		fireEvent.click(checkbox('Read on data.dog'));
+		fireEvent.click(limit());
+		// Role validation rejects an attribute granting what its table does not (MISMATCHED_TABLE_ATTR_PERMS).
+		const attributes = getTableEntry(latest.current, 'data', 'dog')?.attribute_permissions ?? [];
+		expect(attributes.length).toBeGreaterThan(0);
+		expect(attributes.every((attribute) => attribute.read === false)).toBe(true);
+	});
+
+	it('scopes structure_user to selected databases and hides their table grid', () => {
+		const latest = renderEditor({ data: { tables: {} } });
+
+		fireEvent.click(screen.getByRole('radio', { name: /Selected databases/ }));
+		fireEvent.click(checkbox('Structure user on data'));
+		expect(latest.current.structure_user).toEqual(['data']);
+		expect(screen.getByText('full access (structure user)')).toBeTruthy();
+		expect(screen.queryByRole('checkbox', { name: 'Read on data.dog' })).toBeNull();
+	});
+
+	it('offers the cluster user type on Harper 4, and to a role that already has it', () => {
+		renderEditor({}, '4.7.40');
+		expect(screen.getByRole('radio', { name: /Cluster user/ })).toBeTruthy();
+		cleanup();
+		renderEditor({ cluster_user: true });
+		expect(screen.getByRole('radio', { name: /Cluster user/ }).getAttribute('aria-checked')).toBe('true');
+	});
+});
diff --git a/src/features/instance/config/roles/editor/RoleVisualEditor.tsx b/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
new file mode 100644
index 000000000..b9cafb16c
--- /dev/null
+++ b/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
@@ -0,0 +1,700 @@
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@/components/ui/accordion';
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
+import { Button } from '@/components/ui/button';
+import { Label } from '@/components/ui/label';
+import { RadioGroup, RadioGroupItem } from '@/components/ui/radioGroup';
+import { Switch } from '@/components/ui/switch';
+import {
+	ATTRIBUTE_ACTIONS,
+	getAttributeViews,
+	getDatabaseRecord,
+	getEditableDatabaseNames,
+	getPreservedEntries,
+	getRoleType,
+	getTableEntry,
+	getTableEntryInRecord,
+	getTablePrimaryKey,
+	isTableScopedToAttributes,
+	removeEntriesNotInSchema,
+	RoleType,
+	setAttributeAction,
+	setAttributeScoping,
+	setDatabaseAction,
+	setRoleType,
+	setStructureUser,
+	setTableAction,
+	TABLE_ACTIONS,
+} from '@/features/instance/config/roles/editor/rolePermissionModel';
+import { OperationsAllowlistEditor } from '@/features/instance/config/roles/operations/OperationsAllowlistEditor';
+import { supportsOperationsAllowlist } from '@/features/instance/config/roles/operations/operationsCatalog';
+import {
+	InstanceDatabaseMap,
+	InstanceDatabaseTableMap,
+	InstanceTable,
+	LocalRoleAttributePermissionTable,
+	LocalRolePermission,
+	LocalRolePermissionTable,
+} from '@/integrations/api/api.patch';
+import {
+	getOperationsAllowlist,
+	RESERVED_PERMISSION_KEYS,
+	rolePreventsOperationsAllowlist,
+	structureUserDdlScope,
+	withOperations,
+} from '@/integrations/api/localRolePermission';
+import { cn } from '@/lib/cn';
+import { wasAReleasedBeforeB } from '@/lib/string/wasAReleasedBeforeB';
+import { ChevronDownIcon, ChevronRightIcon, TriangleAlertIcon } from 'lucide-react';
+import {
+	type ComponentProps,
+	Fragment,
+	memo,
+	useCallback,
+	useId,
+	useLayoutEffect,
+	useMemo,
+	useRef,
+	useState,
+} from 'react';
+
+const ACTION_LABELS = { read: 'Read', insert: 'Insert', update: 'Update', delete: 'Delete' } as const;
+
+/**
+ * The GUI half of the role editor (HarperFast/studio#1634): renders a parsed permission document
+ * against the instance schema and reports every edit as the whole next document. Rendering what
+ * Harper would enforce, not just what is stored: a table the role does not mention shows as no
+ * access, and a scoped table shows each attribute's effective access.
+ */
+export function RoleVisualEditor({
+	permission,
+	onChange,
+	instanceDatabaseMap,
+	version,
+	readOnly,
+}: {
+	permission: LocalRolePermission;
+	onChange: (next: LocalRolePermission) => void;
+	instanceDatabaseMap: InstanceDatabaseMap;
+	version: string;
+	readOnly?: boolean;
+}) {
+	const roleType = getRoleType(permission);
+	const structureUser = permission.structure_user;
+	const operationsSupported = supportsOperationsAllowlist(version);
+	const databaseNames = useMemo(
+		() => getEditableDatabaseNames(instanceDatabaseMap, version),
+		[instanceDatabaseMap, version],
+	);
+	const preserved = useMemo(
+		() => getPreservedEntries(permission, instanceDatabaseMap, version),
+		[permission, instanceDatabaseMap, version],
+	);
+	// Keyed on the serialized form so edits elsewhere keep the array identity, and with it the
+	// picker's own state, stable.
+	const operationsJson = JSON.stringify(getOperationsAllowlist(permission) ?? null);
+	const operationsValue = useMemo(() => JSON.parse(operationsJson) as string[] | null ?? undefined, [operationsJson]);
+
+	return (
+		<div className="flex flex-col gap-6">
+			{preserved.notInSchema.length > 0 && (
+				<Alert variant="warning">
+					<TriangleAlertIcon />
+					<AlertTitle>This role names things this instance's schema doesn't have</AlertTitle>
+					<AlertDescription>
+						<p>
+							{preserved.notInSchema.join(', ')}. Harper refuses to save a role that names a database or table that
+							doesn't exist, so remove them before saving.
+						</p>
+						{!readOnly && (
+							<Button
+								type="button"
+								size="sm"
+								variant="defaultOutline"
+								className="mt-2"
+								onClick={() => onChange(removeEntriesNotInSchema(permission, instanceDatabaseMap, version))}
+							>
+								Remove them
+							</Button>
+						)}
+					</AlertDescription>
+				</Alert>
+			)}
+
+			<RoleTypeSection
+				permission={permission}
+				roleType={roleType}
+				version={version}
+				readOnly={readOnly}
+				onChange={onChange}
+			/>
+
+			{roleType === 'standard' && (
+				<StructureUserSection
+					permission={permission}
+					databaseNames={databaseNames}
+					readOnly={readOnly}
+					onChange={onChange}
+				/>
+			)}
+
+			{operationsSupported && (
+				<section className="flex flex-col gap-2" aria-label="Operations">
+					<h3 className="text-sm font-medium">Operations</h3>
+					<OperationsAllowlistEditor
+						value={operationsValue}
+						onChange={(next) => onChange(withOperations(permission, next))}
+						version={version}
+						allowlistRejected={rolePreventsOperationsAllowlist(permission)}
+						structureUserDdl={structureUserDdlScope(permission)}
+						disabled={readOnly}
+					/>
+				</section>
+			)}
+
+			{roleType === 'standard' && structureUser !== true && (
+				<TablePermissionsSection
+					permission={permission}
+					instanceDatabaseMap={instanceDatabaseMap}
+					databaseNames={databaseNames}
+					structureDatabases={Array.isArray(structureUser) ? structureUser : []}
+					readOnly={readOnly}
+					onChange={onChange}
+				/>
+			)}
+
+			{preserved.notShown.length > 0 && (
+				<p className="text-xs text-muted-foreground italic">
+					Also kept as they are, but not shown here:{' '}
+					{preserved.notShown.join(', ')}. Use “Edit as JSON” to see or change them.
+				</p>
+			)}
+		</div>
+	);
+}
+
+/** Whether saving will drop anything beside the role's own flag (see preparePermissionForSave). */
+function carriesOtherPermissions(permission: LocalRolePermission, flag: 'super_user' | 'cluster_user'): boolean {
+	return Object.keys(permission).some((key) => key !== flag && permission[key] !== false);
+}
+
+function RoleTypeSection({
+	permission,
+	roleType,
+	version,
+	readOnly,
+	onChange,
+}: {
+	permission: LocalRolePermission;
+	roleType: RoleType;
+	version: string;
+	readOnly?: boolean;
+	onChange: (next: LocalRolePermission) => void;
+}) {
+	const id = useId();
+	// Only Harper 4 gives this flag a meaning (it marks the role of the user that connects cluster
+	// nodes); nothing in Harper 5 reads it, so it is offered there only to a role that already has it.
+	const offerClusterUser = roleType === 'cluster_user' || !wasAReleasedBeforeB('5.0.0', version);
+	const dropsOthers = roleType !== 'standard' && carriesOtherPermissions(permission, roleType);
+	return (
+		<section className="flex flex-col gap-2" aria-labelledby={`${id}-heading`}>
+			<h3 id={`${id}-heading`} className="text-sm font-medium">Role type</h3>
+			<RadioGroup
+				value={roleType}
+				onValueChange={(value) => onChange(setRoleType(permission, value as RoleType))}
+				disabled={readOnly}
+				aria-labelledby={`${id}-heading`}
+			>
+				<RadioOption id={`${id}-standard`} value="standard" label="Standard">
+					Access comes from the database and table permissions below.
+				</RadioOption>
+				<RadioOption id={`${id}-super`} value="super_user" label="Super user">
+					Bypasses per-table permissions.
+				</RadioOption>
+				{offerClusterUser && (
+					<RadioOption id={`${id}-cluster`} value="cluster_user" label="Cluster user">
+						Harper 4 uses this role type for the user that connects cluster nodes.
+					</RadioOption>
+				)}
+			</RadioGroup>
+			{dropsOthers && (
+				<p className="text-xs text-warning">
+					Saving keeps only the <span className="font-mono">{roleType}</span> flag: Harper rejects a{' '}
+					{roleType === 'super_user' ? 'super user' : 'cluster user'}{' '}
+					role that carries any other permission, so this role's other settings are removed.
+				</p>
+			)}
+		</section>
+	);
+}
+
+function RadioOption({ id, value, label, children }: { id: string; value: string; label: string; children: string }) {
+	return (
+		<div className="flex items-start gap-2">
+			<RadioGroupItem id={id} value={value} className="mt-0.5" />
+			<Label htmlFor={id} className="flex flex-col items-start gap-1 font-normal">
+				<span className="font-medium">{label}</span>
+				<span className="text-xs text-muted-foreground">{children}</span>
+			</Label>
+		</div>
+	);
+}
+
+function StructureUserSection({
+	permission,
+	databaseNames,
+	readOnly,
+	onChange,
+}: {
+	permission: LocalRolePermission;
+	databaseNames: string[];
+	readOnly?: boolean;
+	onChange: (next: LocalRolePermission) => void;
+}) {
+	const id = useId();
+	const structureUser = permission.structure_user;
+	const mode = structureUser === true ? 'all' : Array.isArray(structureUser) ? 'selected' : 'off';
+	const selected = Array.isArray(structureUser) ? structureUser : [];
+	// Lets "Selected databases" → another mode → back restore the picks instead of starting empty.
+	const lastSelectionRef = useRef<string[]>(selected);
+	if (Array.isArray(structureUser)) {
+		lastSelectionRef.current = structureUser;
+	}
+	const listed = [...databaseNames, ...selected.filter((name) => !databaseNames.includes(name))];
+	const hasTablePermissions = Object.keys(permission).some((key) => !RESERVED_PERMISSION_KEYS.has(key));
+
+	const onModeChange = (next: string) => {
+		onChange(
+			setStructureUser(permission, next === 'all' ? true : next === 'selected' ? lastSelectionRef.current : false),
+		);
+	};
+	const toggleDatabase = (name: string) => {
+		onChange(setStructureUser(
+			permission,
+			selected.includes(name) ? selected.filter((entry) => entry !== name) : [...selected, name],
+		));
+	};
+
+	return (
+		<section className="flex flex-col gap-2" aria-labelledby={`${id}-heading`}>
+			<h3 id={`${id}-heading`} className="text-sm font-medium">Structure user</h3>
+			<RadioGroup value={mode} onValueChange={onModeChange} disabled={readOnly} aria-labelledby={`${id}-heading`}>
+				<RadioOption id={`${id}-off`} value="off" label="No">
+					Creating and dropping databases, tables and attributes needs super user, or an operations list that grants it.
+				</RadioOption>
+				<RadioOption id={`${id}-all`} value="all" label="All databases">
+					Can create and drop databases, tables and attributes, and can read, insert, update and delete in every table.
+				</RadioOption>
+				<RadioOption id={`${id}-selected`} value="selected" label="Selected databases">
+					Can create and drop tables and attributes in the selected databases, and can read, insert, update and delete
+					in their tables. Creating and dropping databases isn't included.
+				</RadioOption>
+			</RadioGroup>
+			{mode !== 'off' && permission.operations !== undefined && (
+				<p className="text-xs text-muted-foreground">The operations list below can still deny some of these.</p>
+			)}
+			{mode === 'all' && hasTablePermissions && (
+				<p className="text-xs text-warning">
+					Per-table permissions don't apply to this role, so they are removed when you save.
+				</p>
+			)}
+			{mode === 'selected' && (
+				<div className="ml-6 flex flex-col gap-1">
+					{listed.length === 0 && <p className="text-xs text-muted-foreground">This instance has no databases.</p>}
+					{listed.map((name) => (
+						<Label key={name} className="flex items-center gap-2 font-normal">
+							<PermissionCheckbox
+								checked={selected.includes(name)}
+								onChange={() => toggleDatabase(name)}
+								disabled={readOnly}
+								aria-label={`Structure user on ${name}`}
+							/>
+							<span className="font-mono text-xs">{name}</span>
+							{!databaseNames.includes(name) && (
+								<span className="text-xs text-muted-foreground">(not in this instance's schema)</span>
+							)}
+						</Label>
+					))}
+				</div>
+			)}
+		</section>
+	);
+}
+
+type PermissionPatch = (permission: LocalRolePermission) => LocalRolePermission;
+
+function TablePermissionsSection({
+	permission,
+	instanceDatabaseMap,
+	databaseNames,
+	structureDatabases,
+	readOnly,
+	onChange,
+}: {
+	permission: LocalRolePermission;
+	instanceDatabaseMap: InstanceDatabaseMap;
+	databaseNames: string[];
+	structureDatabases: string[];
+	readOnly?: boolean;
+	onChange: (next: LocalRolePermission) => void;
+}) {
+	// Databases the role already grants something on open expanded, so the role reads at a glance;
+	// a role with no grants yet opens the first one as a starting point.
+	const [openDatabases, setOpenDatabases] = useState<string[]>(() => {
+		const granted = databaseNames.filter((databaseName) =>
+			Object.keys(instanceDatabaseMap[databaseName]).some((tableName) => {
+				const entry = getTableEntry(permission, databaseName, tableName);
+				return entry && TABLE_ACTIONS.some((action) => entry[action] === true);
+			})
+		);
+		return granted.length ? granted : databaseNames.slice(0, 1);
+	});
+	// Survives turning attribute scoping off and on again within the session, like the operations
+	// switch does for its allowlist.
+	const scopingRestoreRef = useRef(new Map<string, LocalRoleAttributePermissionTable[]>());
+	// One stable updater for every row, applied to the latest document: rows are memoized on their
+	// own database record, so on a large schema an edit re-renders only the database it touched.
+	const latestRef = useRef({ permission, onChange });
+	latestRef.current = { permission, onChange };
+	const update = useCallback((patch: PermissionPatch) => {
+		latestRef.current.onChange(patch(latestRef.current.permission));
+	}, []);
+
+	return (
+		<section className="flex flex-col gap-2" aria-label="Table permissions">
+			<h3 className="text-sm font-medium">Table permissions</h3>
+			<p className="text-xs text-muted-foreground">
+				A table without a checked permission has no access. Delete always applies to whole records.
+			</p>
+			{databaseNames.length === 0 && <p className="text-sm text-muted-foreground">This instance has no databases.</p>}
+			<Accordion type="multiple" value={openDatabases} onValueChange={setOpenDatabases} className="rounded-md border">
+				{databaseNames.map((databaseName) => (
+					<DatabaseSection
+						key={databaseName}
+						databaseName={databaseName}
+						tables={instanceDatabaseMap[databaseName]}
+						record={getDatabaseRecord(permission, databaseName)}
+						structureScoped={structureDatabases.includes(databaseName)}
+						readOnly={readOnly}
+						update={update}
+						scopingRestore={scopingRestoreRef.current}
+					/>
+				))}
+			</Accordion>
+		</section>
+	);
+}
+
+const DatabaseSection = memo(function DatabaseSection({
+	databaseName,
+	tables,
+	record,
+	structureScoped,
+	readOnly,
+	update,
+	scopingRestore,
+}: {
+	databaseName: string;
+	tables: InstanceDatabaseTableMap;
+	record: Record<string, unknown> | undefined;
+	structureScoped: boolean;
+	readOnly?: boolean;
+	update: (patch: PermissionPatch) => void;
+	scopingRestore: Map<string, LocalRoleAttributePermissionTable[]>;
+}) {
+	const tableNames = Object.keys(tables);
+	const entries = tableNames.map((tableName) => getTableEntryInRecord(record, tableName));
+	const grantedCount = entries.filter((entry) => entry && TABLE_ACTIONS.some((action) => entry[action] === true))
+		.length;
+
+	return (
+		<AccordionItem value={databaseName} className="px-3">
+			<AccordionTrigger className="py-3">
+				<span className="flex flex-wrap items-baseline gap-2">
+					<span className="font-mono">{databaseName}</span>
+					<span className="text-xs font-normal text-muted-foreground">
+						{structureScoped
+							? 'full access (structure user)'
+							: `${grantedCount} of ${tableNames.length} ${tableNames.length === 1 ? 'table' : 'tables'} with access`}
+					</span>
+				</span>
+			</AccordionTrigger>
+			<AccordionContent>
+				{structureScoped
+					? (
+						<p className="text-xs text-muted-foreground">
+							As a structure user on this database, the role can read, insert, update and delete in every table here, so
+							per-table permissions don't apply to it.
+						</p>
+					)
+					: tableNames.length === 0
+					? <p className="text-xs text-muted-foreground">No tables.</p>
+					: (
+						<div className="overflow-x-auto">
+							<table className="w-full text-sm">
+								<thead>
+									<tr className="border-b text-xs text-muted-foreground">
+										<th className="py-1 pr-2 text-left font-normal">Table</th>
+										{TABLE_ACTIONS.map((action) => (
+											<th key={action} className="px-2 py-1 text-center font-normal">{ACTION_LABELS[action]}</th>
+										))}
+										<th className="py-1 pl-2 text-left font-normal">Attributes</th>
+									</tr>
+								</thead>
+								<tbody>
+									<tr className="border-b">
+										<td className="py-1 pr-2 text-xs text-muted-foreground">All tables</td>
+										{TABLE_ACTIONS.map((action) => {
+											const count = entries.filter((entry) => entry?.[action] === true).length;
+											return (
+												<td key={action} className="px-2 py-1 text-center">
+													<PermissionCheckbox
+														checked={count === tableNames.length}
+														indeterminate={count > 0 && count < tableNames.length}
+														disabled={readOnly}
+														aria-label={`${ACTION_LABELS[action]} on every table in ${databaseName}`}
+														onChange={() =>
+															update((permission) =>
+																setDatabaseAction(
+																	permission,
+																	databaseName,
+																	tableNames,
+																	action,
+																	count < tableNames.length,
+																)
+															)}
+													/>
+												</td>
+											);
+										})}
+										<td />
+									</tr>
+									{tableNames.map((tableName, index) => (
+										<TableRows
+											key={tableName}
+											databaseName={databaseName}
+											tableName={tableName}
+											schemaTable={tables[tableName]}
+											entry={entries[index]}
+											readOnly={readOnly}
+											update={update}
+											scopingRestore={scopingRestore}
+										/>
+									))}
+								</tbody>
+							</table>
+						</div>
+					)}
+			</AccordionContent>
+		</AccordionItem>
+	);
+});
+
+const TableRows = memo(function TableRows({
+	databaseName,
+	tableName,
+	schemaTable,
+	entry,
+	readOnly,
+	update,
+	scopingRestore,
+}: {
+	databaseName: string;
+	tableName: string;
+	schemaTable: InstanceTable;
+	entry: LocalRolePermissionTable | undefined;
+	readOnly?: boolean;
+	update: (patch: PermissionPatch) => void;
+	scopingRestore: Map<string, LocalRoleAttributePermissionTable[]>;
+}) {
+	const attributeNames = useMemo(
+		() => schemaTable.attributes.map((attribute) => attribute.attribute),
+		[schemaTable],
+	);
+	const primaryKey = getTablePrimaryKey(schemaTable);
+	const scoped = isTableScopedToAttributes(entry);
+	const [expanded, setExpanded] = useState(false);
+	const label = `${databaseName}.${tableName}`;
+	const views = scoped && entry ? getAttributeViews(entry, attributeNames, primaryKey) : [];
+	const accessible = views.filter((view) => ATTRIBUTE_ACTIONS.some((action) => view[action])).length;
+	const restoreKey = `${databaseName}\u0000${tableName}`;
+
+	const onScopingChanged = (next: boolean) => {
+		if (!next && entry?.attribute_permissions) {
+			scopingRestore.set(restoreKey, entry.attribute_permissions);
+		}
+		update((permission) =>
+			setAttributeScoping(
+				permission,
+				databaseName,
+				tableName,
+				next,
+				attributeNames,
+				next ? scopingRestore.get(restoreKey) : undefined,
+			)
+		);
+	};
+
+	return (
+		<Fragment>
+			<tr className="border-b last:border-0">
+				<td className="py-1 pr-2 font-mono text-xs">{tableName}</td>
+				{TABLE_ACTIONS.map((action) => (
+					<td key={action} className="px-2 py-1 text-center">
+						<PermissionCheckbox
+							checked={entry?.[action] === true}
+							disabled={readOnly}
+							aria-label={`${ACTION_LABELS[action]} on ${label}`}
+							onChange={(event) => {
+								const { checked } = event.target;
+								update((permission) => setTableAction(permission, databaseName, tableName, action, checked));
+							}}
+						/>
+					</td>
+				))}
+				<td className="py-1 pl-2">
+					<button
+						type="button"
+						className="flex items-center gap-1 text-xs text-muted-foreground hover:text-foreground"
+						onClick={() => setExpanded((value) => !value)}
+						aria-expanded={expanded}
+						aria-label={`Attribute permissions for ${label}`}
+					>
+						{expanded ? <ChevronDownIcon className="size-3" /> : <ChevronRightIcon className="size-3" />}
+						{scoped ? `${accessible} of ${attributeNames.length}` : 'All'}
+					</button>
+				</td>
+			</tr>
+			{expanded && (
+				<tr className="border-b bg-muted/30">
+					<td colSpan={TABLE_ACTIONS.length + 2} className="px-3 py-2">
+						<AttributePanel
+							label={label}
+							scoped={scoped}
+							views={views}
+							disabled={readOnly || attributeNames.length === 0}
+							onScopingChanged={onScopingChanged}
+							onActionChanged={(attributeName, action, value) =>
+								update((permission) =>
+									setAttributeAction(
+										permission,
+										databaseName,
+										tableName,
+										attributeNames,
+										primaryKey,
+										attributeName,
+										action,
+										value,
+									)
+								)}
+						/>
+					</td>
+				</tr>
+			)}
+		</Fragment>
+	);
+});
+
+function AttributePanel({
+	label,
+	scoped,
+	views,
+	disabled,
+	onScopingChanged,
+	onActionChanged,
+}: {
+	label: string;
+	scoped: boolean;
+	views: ReturnType<typeof getAttributeViews>;
+	disabled?: boolean;
+	onScopingChanged: (scoped: boolean) => void;
+	onActionChanged: (attributeName: string, action: (typeof ATTRIBUTE_ACTIONS)[number], value: boolean) => void;
+}) {
+	const id = useId();
+	const derivedKey = views.find((view) => view.derived);
+	return (
+		<div className="flex flex-col gap-2">
+			<div className="flex items-center gap-2">
+				<Switch
+					id={id}
+					checked={scoped}
+					onCheckedChange={onScopingChanged}
+					disabled={disabled}
+					aria-label={`Limit ${label} to specific attributes`}
+				/>
+				<Label htmlFor={id} className="font-normal">Limit to specific attributes</Label>
+			</div>
+			<p className="text-xs text-muted-foreground">
+				{scoped
+					? "Only the access checked here applies. An attribute with nothing checked has no access, including attributes added to the table later. Computed attributes aren't listed here; grant them in the JSON."
+					: "The table's read, insert and update apply to every attribute."}
+			</p>
+			{scoped && (
+				<table className="w-full max-w-md text-xs">
+					<thead>
+						<tr className="text-muted-foreground">
+							<th className="py-1 pr-2 text-left font-normal">Attribute</th>
+							{ATTRIBUTE_ACTIONS.map((action) => (
+								<th key={action} className="px-2 py-1 text-center font-normal">{ACTION_LABELS[action]}</th>
+							))}
+						</tr>
+					</thead>
+					<tbody>
+						{views.map((view) => (
+							<tr key={view.name}>
+								<td className="py-0.5 pr-2 font-mono">
+									{view.name}
+									{view.isPrimaryKey && <span className="ml-1 font-sans text-muted-foreground">(primary key)</span>}
+								</td>
+								{ATTRIBUTE_ACTIONS.map((action) => {
+									const timestampOnlyRead = view.isTimestamp && action !== 'read';
+									return (
+										<td key={action} className="px-2 py-0.5 text-center">
+											<PermissionCheckbox
+												checked={view[action]}
+												disabled={disabled || timestampOnlyRead}
+												title={timestampOnlyRead ? 'Harper applies only read to this timestamp attribute.' : undefined}
+												aria-label={`${ACTION_LABELS[action]} on ${label}.${view.name}`}
+												onChange={(event) => onActionChanged(view.name, action, event.target.checked)}
+											/>
+										</td>
+									);
+								})}
+							</tr>
+						))}
+					</tbody>
+				</table>
+			)}
+			{scoped && derivedKey && (
+				<p className="text-xs text-muted-foreground">
+					The primary key <span className="font-mono">{derivedKey.name}</span>{' '}
+					isn't listed, so it gets whatever access any other attribute has. Changing it here sets it explicitly.
+				</p>
+			)}
+			{scoped && views.some((view) => view.isTimestamp) && (
+				<p className="text-xs text-muted-foreground">Harper applies only read to timestamp attributes.</p>
+			)}
+		</div>
+	);
+}
+
+/** `indeterminate` is a DOM property with no attribute behind it, so it has to be set on the node. */
+function PermissionCheckbox({
+	indeterminate = false,
+	className,
+	...props
+}: ComponentProps<'input'> & { indeterminate?: boolean }) {
+	const ref = useRef<HTMLInputElement>(null);
+	useLayoutEffect(() => {
+		if (ref.current) {
+			ref.current.indeterminate = indeterminate;
+		}
+	}, [indeterminate]);
+	return (
+		<input
+			ref={ref}
+			type="checkbox"
+			className={cn('size-4 cursor-pointer align-middle disabled:cursor-not-allowed disabled:opacity-50', className)}
+			{...props}
+		/>
+	);
+}
diff --git a/src/features/instance/config/roles/editor/rolePermissionModel.test.ts b/src/features/instance/config/roles/editor/rolePermissionModel.test.ts
new file mode 100644
index 000000000..5ffd42690
--- /dev/null
+++ b/src/features/instance/config/roles/editor/rolePermissionModel.test.ts
@@ -0,0 +1,333 @@
+import {
+	getAttributeViews,
+	getEditableDatabaseNames,
+	getPreservedEntries,
+	getRoleType,
+	getTableEntry,
+	getVisualEditorBlockers,
+	isTableScopedToAttributes,
+	parseRolePermissionText,
+	removeEntriesNotInSchema,
+	serializeRolePermission,
+	setAttributeAction,
+	setAttributeScoping,
+	setDatabaseAction,
+	setRoleType,
+	setStructureUser,
+	setTableAction,
+} from '@/features/instance/config/roles/editor/rolePermissionModel';
+import { InstanceDatabaseMap, InstanceTable, LocalRolePermission } from '@/integrations/api/api.patch';
+import { describe, expect, it } from 'vitest';
+
+function table(name: string, attributes: string[], primaryKey = 'id'): InstanceTable {
+	return {
+		schema: 'data',
+		name,
+		primary_key: primaryKey,
+		audit: false,
+		schema_defined: true,
+		db_size: 0,
+		sources: [],
+		attributes: attributes.map((attribute) => ({ attribute, is_primary_key: attribute === primaryKey })),
+	} as unknown as InstanceTable;
+}
+
+const schema: InstanceDatabaseMap = {
+	data: {
+		dog: table('dog', ['id', 'name', 'breed', '__createdtime__']),
+		cat: table('cat', ['id', 'name']),
+	},
+	dev: { thing: table('thing', ['id']) },
+};
+const VERSION = '5.3.1';
+const dogAttributes = ['id', 'name', 'breed', '__createdtime__'];
+
+const entry = (read: boolean, insert = false, update = false, del = false, attributes: unknown = []) => ({
+	read,
+	insert,
+	update,
+	delete: del,
+	attribute_permissions: attributes,
+});
+
+const asPermission = (value: unknown) => value as LocalRolePermission;
+
+describe('parseRolePermissionText', () => {
+	it('returns only JSON objects', () => {
+		expect(parseRolePermissionText('{"super_user":true}')).toEqual({ super_user: true });
+		expect(parseRolePermissionText('[]')).toBeNull();
+		expect(parseRolePermissionText('null')).toBeNull();
+		expect(parseRolePermissionText('{"super_user":')).toBeNull();
+		expect(parseRolePermissionText('')).toBeNull();
+	});
+});
+
+describe('getEditableDatabaseNames', () => {
+	it('skips a database named operations once the key is the allowlist', () => {
+		const withOperations = { ...schema, operations: { t: table('t', ['id']) } };
+		expect(getEditableDatabaseNames(withOperations, '5.3.1')).toEqual(['data', 'dev']);
+		expect(getEditableDatabaseNames(withOperations, '4.7.40')).toEqual(['data', 'dev', 'operations']);
+	});
+});
+
+describe('getVisualEditorBlockers', () => {
+	it('accepts the shapes Harper stores, including null attribute_permissions', () => {
+		const permission = asPermission({
+			super_user: false,
+			structure_user: ['dev'],
+			operations: ['read_only'],
+			data: { tables: { dog: entry(true, false, false, false, null), cat: entry(true) } },
+		});
+		expect(getVisualEditorBlockers(permission, schema, VERSION)).toEqual([]);
+	});
+
+	it('names every shape the GUI cannot represent', () => {
+		const permission = asPermission({
+			super_user: 'yes',
+			structure_user: { dev: true },
+			operations: { tables: {} },
+			data: {
+				tables: {
+					dog: { read: true, insert: false, update: false, attribute_permissions: 'all' },
+					cat: entry(true, false, false, false, [{ attribute_name: 'name', read: true }, { read: true }]),
+				},
+			},
+			dev: 'everything',
+		});
+		const blockers = getVisualEditorBlockers(permission, schema, VERSION);
+		expect(blockers).toEqual([
+			'"super_user" must be true or false.',
+			'"structure_user" must be true, false, or a list of database names.',
+			'"operations" is not a list of operation names.',
+			'"data.dog": delete must each be true or false.',
+			'"data.dog.attribute_permissions" must be a list.',
+			'"data.cat.attribute_permissions": "name" needs read, insert and update set to true or false.',
+			'"data.cat.attribute_permissions" has an entry without an attribute_name.',
+			'The entry for database "dev" is not an object.',
+		]);
+	});
+
+	it('refuses both exclusive flags, duplicate attributes and the pre-2.2 format', () => {
+		expect(getVisualEditorBlockers({ super_user: true, cluster_user: true }, schema, VERSION)).toEqual([
+			'"super_user" and "cluster_user" cannot both be true.',
+		]);
+		const duplicated = asPermission({
+			data: {
+				tables: {
+					cat: entry(true, false, false, false, [
+						{ attribute_name: 'name', read: true, insert: false, update: false },
+						{ attribute_name: 'name', read: false, insert: false, update: false },
+					]),
+				},
+			},
+		});
+		expect(getVisualEditorBlockers(duplicated, schema, VERSION)).toEqual([
+			'"data.cat.attribute_permissions" lists "name" more than once.',
+		]);
+		const legacy = asPermission({ data: { tables: { cat: { ...entry(true), attribute_restrictions: [] } } } });
+		expect(getVisualEditorBlockers(legacy, schema, VERSION)).toHaveLength(1);
+		expect(getVisualEditorBlockers({}, schema, '2.1.2')).toHaveLength(1);
+		// An unparseable version is not evidence of a pre-2.2 instance.
+		expect(getVisualEditorBlockers({}, schema, 'unknown')).toEqual([]);
+	});
+
+	it('ignores the shape of entries the GUI does not render', () => {
+		const permission = asPermission({ gone: 42, data: { tables: { removed: 'x' } } });
+		expect(getVisualEditorBlockers(permission, schema, VERSION)).toEqual([]);
+	});
+});
+
+describe('getPreservedEntries / removeEntriesNotInSchema', () => {
+	const permission = asPermission({
+		structure_user: ['dev', 'gone'],
+		gone: { tables: { x: entry(true) } },
+		data: {
+			describe: true,
+			tables: {
+				dog: {
+					...entry(true, false, false, false, [
+						{ attribute_name: 'name', read: true, insert: false, update: false, delete: true },
+						{ attribute_name: 'computed_score', read: true, insert: false, update: false },
+					]),
+					extra: 1,
+				},
+				removed: entry(true),
+			},
+		},
+	});
+
+	it('separates what Harper would reject from what is merely not shown', () => {
+		expect(getPreservedEntries(permission, schema, VERSION)).toEqual({
+			notInSchema: ['structure_user database "gone"', 'database "gone"', 'table "data.removed"'],
+			notShown: [
+				'"data.describe"',
+				'"data.dog.extra"',
+				'"delete" on attribute "data.dog.name"',
+				'attribute "data.dog.computed_score"',
+			],
+		});
+	});
+
+	it('removes only the entries not in the schema and keeps the rest verbatim', () => {
+		const cleaned = removeEntriesNotInSchema(permission, schema, VERSION);
+		expect(cleaned).toEqual({
+			structure_user: ['dev'],
+			data: { describe: true, tables: { dog: (permission.data as { tables: { dog: unknown } }).tables.dog } },
+		});
+		expect(getPreservedEntries(cleaned, schema, VERSION).notInSchema).toEqual([]);
+	});
+
+	it('reports an inert operations value below the allowlist floor without removing it', () => {
+		const old = asPermission({ operations: ['read_only'] });
+		expect(getPreservedEntries(old, schema, '4.7.40').notShown).toEqual([
+			'"operations" (has no effect before Harper 5.0)',
+		]);
+		expect(removeEntriesNotInSchema(old, schema, '4.7.40')).toEqual(old);
+	});
+});
+
+describe('role type and structure_user', () => {
+	it('sets the exclusive flag and keeps the rest of the document for the session', () => {
+		const permission = asPermission({ super_user: false, data: { tables: { cat: entry(true) } } });
+		const superUser = setRoleType(permission, 'super_user');
+		expect(superUser).toEqual({ super_user: true, data: permission.data });
+		expect(getRoleType(superUser)).toBe('super_user');
+
+		const back = setRoleType(superUser, 'standard');
+		expect(back).toEqual(permission);
+		// A flag the document never carried is not added just to say false.
+		expect(setRoleType({}, 'standard')).toEqual({});
+		expect(setRoleType({ super_user: true }, 'cluster_user')).toEqual({ super_user: false, cluster_user: true });
+	});
+
+	it('writes structure_user to the top and does not add a false one', () => {
+		const permission = asPermission({ data: { tables: {} } });
+		expect(Object.keys(setStructureUser(permission, ['dev']))).toEqual(['structure_user', 'data']);
+		expect(setStructureUser(permission, false)).toBe(permission);
+		expect(setStructureUser({ structure_user: true }, false)).toEqual({ structure_user: false });
+	});
+});
+
+describe('table actions', () => {
+	it('creates the entry Harper requires when granting on an unlisted table, and is a no-op when revoking one', () => {
+		const granted = setTableAction({}, 'data', 'cat', 'read', true);
+		expect(granted).toEqual({ data: { tables: { cat: entry(true) } } });
+		expect(setTableAction({}, 'data', 'cat', 'read', false)).toEqual({});
+	});
+
+	it('preserves every key it does not touch', () => {
+		const permission = asPermission({
+			data: { describe: true, tables: { cat: { ...entry(true, false, false, false, null), extra: 1 } } },
+		});
+		expect(setTableAction(permission, 'data', 'cat', 'insert', true)).toEqual({
+			data: { describe: true, tables: { cat: { ...entry(true, true, false, false, null), extra: 1 } } },
+		});
+	});
+
+	it('revokes an action on the attributes too, which role validation requires', () => {
+		const scoped = asPermission({
+			data: {
+				tables: {
+					dog: entry(true, true, false, false, [
+						{ attribute_name: 'name', read: true, insert: true, update: false },
+						{ attribute_name: 'breed', read: false, insert: true, update: false },
+					]),
+				},
+			},
+		});
+		const next = setTableAction(scoped, 'data', 'dog', 'insert', false);
+		expect(getTableEntry(next, 'data', 'dog')?.attribute_permissions).toEqual([
+			{ attribute_name: 'name', read: true, insert: false, update: false },
+			{ attribute_name: 'breed', read: false, insert: false, update: false },
+		]);
+	});
+
+	it('sets a database-wide action in one pass, keeping table order', () => {
+		const permission = asPermission({ data: { tables: { cat: entry(false, true) } } });
+		const next = setDatabaseAction(permission, 'data', ['dog', 'cat'], 'read', true);
+		expect(next).toEqual({ data: { tables: { cat: entry(true, true), dog: entry(true) } } });
+		expect(Object.keys((next.data as { tables: object }).tables)).toEqual(['cat', 'dog']);
+		expect(setDatabaseAction({}, 'data', ['dog', 'cat'], 'read', false)).toEqual({});
+	});
+
+	it('keeps a __proto__ database and table as own keys', () => {
+		const next = setTableAction({}, '__proto__', '__proto__', 'read', true);
+		const roundTripped = JSON.parse(JSON.stringify(next)) as object;
+		const database = Object.getOwnPropertyDescriptor(roundTripped, '__proto__')?.value as { tables: object };
+		expect(Object.getOwnPropertyDescriptor(database.tables, '__proto__')?.value).toEqual(entry(true));
+		expect(getTableEntry(next, '__proto__', '__proto__')).toEqual(entry(true));
+	});
+});
+
+describe('attribute scoping', () => {
+	it('lists every attribute with the table access when turned on, so nothing changes at that moment', () => {
+		const permission = asPermission({ data: { tables: { dog: entry(true, true) } } });
+		const scoped = setAttributeScoping(permission, 'data', 'dog', true, dogAttributes);
+		const dog = getTableEntry(scoped, 'data', 'dog');
+		expect(isTableScopedToAttributes(dog)).toBe(true);
+		expect(dog?.attribute_permissions).toEqual([
+			{ attribute_name: 'id', read: true, insert: true, update: false },
+			{ attribute_name: 'name', read: true, insert: true, update: false },
+			{ attribute_name: 'breed', read: true, insert: true, update: false },
+			// Harper only applies read to a timestamp attribute.
+			{ attribute_name: '__createdtime__', read: true, insert: false, update: false },
+		]);
+		const off = setAttributeScoping(scoped, 'data', 'dog', false, dogAttributes);
+		expect(getTableEntry(off, 'data', 'dog')).toEqual(entry(true, true));
+		const restored = setAttributeScoping(off, 'data', 'dog', true, dogAttributes, dog?.attribute_permissions ?? []);
+		expect(restored).toEqual(scoped);
+	});
+
+	it('derives an unlisted primary key from the listed attributes, as permissionsTranslator does', () => {
+		const dog = entry(true, true, false, false, [
+			{ attribute_name: 'name', read: true, insert: false, update: false },
+			{ attribute_name: '__createdtime__', read: true, insert: true, update: true },
+		]);
+		const views = getAttributeViews(dog as never, dogAttributes, 'id');
+		expect(views.map(({ name, read, insert, update, derived }) => ({ name, read, insert, update, derived }))).toEqual([
+			{ name: 'id', read: true, insert: false, update: false, derived: true },
+			{ name: 'name', read: true, insert: false, update: false, derived: false },
+			// Not listed in a scoped table: no access.
+			{ name: 'breed', read: false, insert: false, update: false, derived: false },
+			// Its stored insert/update are ignored by Harper, so they do not reach the key either.
+			{ name: '__createdtime__', read: true, insert: false, update: false, derived: false },
+		]);
+	});
+
+	it('adds an unlisted attribute with its effective access before flipping one action', () => {
+		const permission = asPermission({
+			data: {
+				tables: {
+					dog: entry(true, false, false, false, [
+						{ attribute_name: 'name', read: true, insert: false, update: false },
+					]),
+				},
+			},
+		});
+		// The derived key keeps read when it becomes explicit, so revoking nothing else by accident.
+		const pkInsert = setAttributeAction(permission, 'data', 'dog', dogAttributes, 'id', 'id', 'insert', true);
+		const dog = getTableEntry(pkInsert, 'data', 'dog');
+		expect(dog?.attribute_permissions).toEqual([
+			{ attribute_name: 'name', read: true, insert: false, update: false },
+			{ attribute_name: 'id', read: true, insert: true, update: false },
+		]);
+		// Granting an attribute an action its table lacks grants it on the table too.
+		expect(dog?.insert).toBe(true);
+
+		const revoked = setAttributeAction(pkInsert, 'data', 'dog', dogAttributes, 'id', 'name', 'read', false);
+		expect(getTableEntry(revoked, 'data', 'dog')?.attribute_permissions?.[0]).toEqual({
+			attribute_name: 'name',
+			read: false,
+			insert: false,
+			update: false,
+		});
+		expect(getTableEntry(revoked, 'data', 'dog')?.read).toBe(true);
+	});
+});
+
+describe('serializeRolePermission', () => {
+	it('floats the role flags above the databases', () => {
+		const text = serializeRolePermission(asPermission({ data: { tables: {} }, operations: [], super_user: false }));
+		expect(Object.keys(JSON.parse(text) as object)).toEqual(['super_user', 'operations', 'data']);
+	});
+});
diff --git a/src/features/instance/config/roles/editor/rolePermissionModel.ts b/src/features/instance/config/roles/editor/rolePermissionModel.ts
new file mode 100644
index 000000000..c7dfbefa4
--- /dev/null
+++ b/src/features/instance/config/roles/editor/rolePermissionModel.ts
@@ -0,0 +1,629 @@
+import { supportsOperationsAllowlist } from '@/features/instance/config/roles/operations/operationsCatalog';
+import {
+	InstanceDatabaseMap,
+	InstanceTable,
+	LocalRoleAttributePermissionAction,
+	LocalRoleAttributePermissionTable,
+	LocalRolePermission,
+	LocalRolePermissionAction,
+	LocalRolePermissionTable,
+} from '@/integrations/api/api.patch';
+import {
+	classifyOperationsValue,
+	getDatabasePermissionRecord,
+	orderPermissionKeys,
+	RESERVED_PERMISSION_KEYS,
+} from '@/integrations/api/localRolePermission';
+import { compareVersions } from '@/lib/string/wasAReleasedBeforeB';
+
+/**
+ * The model behind the visual role editor (HarperFast/studio#1634). The permission JSON stays the
+ * single source of truth: the editor reads the parsed document and every edit here is a
+ * copy-on-write patch of only the keys it touches, so a key the GUI does not model survives a
+ * round-trip by construction rather than by being re-serialized from a model that knows about it.
+ *
+ * The rules encoded below were traced to Harper 5.3.1 (`validation/role_validation.ts`,
+ * `security/permissionsTranslator.js`) and checked against its build.
+ */
+
+export const TABLE_ACTIONS: readonly LocalRolePermissionAction[] = ['read', 'insert', 'update', 'delete'];
+export const ATTRIBUTE_ACTIONS: readonly LocalRoleAttributePermissionAction[] = ['read', 'insert', 'update'];
+
+/** permissionsTranslator applies only `read` to these, whatever the entry says. */
+const TIMESTAMP_ATTRIBUTES: ReadonlySet<string> = new Set(['__createdtime__', '__updatedtime__']);
+const TABLE_ENTRY_KEYS: ReadonlySet<string> = new Set([...TABLE_ACTIONS, 'attribute_permissions']);
+const ATTRIBUTE_ENTRY_KEYS: ReadonlySet<string> = new Set(['attribute_name', ...ATTRIBUTE_ACTIONS]);
+
+export type RoleType = 'standard' | 'super_user' | 'cluster_user';
+
+type PlainRecord = Record<string, unknown>;
+
+function isPlainRecord(value: unknown): value is PlainRecord {
+	return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+// Every key below may be a database, table or attribute name, and Harper permits `__proto__` for
+// all three — so reads use hasOwn and writes rebuild with Object.fromEntries, never assignment.
+function ownValue(record: PlainRecord, key: string): unknown {
+	return Object.hasOwn(record, key) ? record[key] : undefined;
+}
+
+function withKey<T extends object>(record: T, key: string, value: unknown): T {
+	let replaced = false;
+	const entries = Object.entries(record).map(([existingKey, existing]): [string, unknown] => {
+		if (existingKey === key) {
+			replaced = true;
+			return [existingKey, value];
+		}
+		return [existingKey, existing];
+	});
+	if (!replaced) {
+		entries.push([key, value]);
+	}
+	return Object.fromEntries(entries) as T;
+}
+
+function withoutKeys<T extends object>(record: T, keys: ReadonlySet<string>): T {
+	return Object.fromEntries(Object.entries(record).filter(([key]) => !keys.has(key))) as T;
+}
+
+/** The parsed permission document, or null when the text is not a JSON object. */
+export function parseRolePermissionText(text: string | undefined): LocalRolePermission | null {
+	if (!text) {
+		return null;
+	}
+	try {
+		// Not safeParse: it console.errors, and mid-edit text is invalid on most keystrokes.
+		const parsed: unknown = JSON.parse(text);
+		return isPlainRecord(parsed) ? parsed as LocalRolePermission : null;
+	} catch {
+		return null;
+	}
+}
+
+export function serializeRolePermission(permission: LocalRolePermission): string {
+	return JSON.stringify(orderPermissionKeys(permission), null, 2);
+}
+
+/**
+ * Databases the editor offers, in describe_all order. A database named like a reserved permission
+ * key cannot be granted in role JSON, except `operations` below the allowlist floor, where Harper
+ * reserves nothing by that name.
+ */
+export function getEditableDatabaseNames(instanceDatabaseMap: InstanceDatabaseMap, version: string): string[] {
+	const allowlistSupported = supportsOperationsAllowlist(version);
+	return Object.keys(instanceDatabaseMap).filter((name) =>
+		!RESERVED_PERMISSION_KEYS.has(name) || (name === 'operations' && !allowlistSupported)
+	);
+}
+
+export function getTablePrimaryKey(table: InstanceTable): string | undefined {
+	return table.primary_key ?? table.hash_attribute
+		?? table.attributes.find((attribute) => attribute.is_primary_key)?.attribute;
+}
+
+/** Keys of the document that name databases rather than role flags or the allowlist. */
+function getDatabaseKeys(permission: LocalRolePermission, allowlistSupported: boolean): string[] {
+	return Object.keys(permission).filter((key) =>
+		!RESERVED_PERMISSION_KEYS.has(key)
+		|| (key === 'operations' && getDatabasePermissionRecord(permission, key, allowlistSupported) !== undefined)
+	);
+}
+
+/**
+ * Why the visual editor cannot show this document, or an empty list when it can. Anything listed
+ * here is a shape the GUI could only render by guessing or would rewrite on its first edit, so the
+ * JSON view stays authoritative until it is fixed. Most are shapes Harper's role validation
+ * rejects anyway (`role_validation.ts` — flag types, table CRUD booleans, attribute_permissions
+ * array-or-null, attribute entry shape); the operations kinds are the ones the existing notice
+ * explains.
+ */
+export function getVisualEditorBlockers(
+	permission: LocalRolePermission,
+	instanceDatabaseMap: InstanceDatabaseMap,
+	version: string,
+): string[] {
+	if (isLegacyRoleFormat(version)) {
+		return ['This Harper version uses the role format from before 2.2, which only the JSON editor supports.'];
+	}
+	const blockers: string[] = [];
+	const allowlistSupported = supportsOperationsAllowlist(version);
+	for (const flag of ['super_user', 'cluster_user'] as const) {
+		if (Object.hasOwn(permission, flag) && typeof permission[flag] !== 'boolean') {
+			blockers.push(`"${flag}" must be true or false.`);
+		}
+	}
+	if (permission.super_user === true && permission.cluster_user === true) {
+		blockers.push('"super_user" and "cluster_user" cannot both be true.');
+	}
+	const structureUser = permission.structure_user;
+	if (
+		structureUser !== undefined && typeof structureUser !== 'boolean'
+		&& !(Array.isArray(structureUser) && structureUser.every((name) => typeof name === 'string'))
+	) {
+		blockers.push('"structure_user" must be true, false, or a list of database names.');
+	}
+	const operationsKind = classifyOperationsValue(permission, allowlistSupported);
+	if (operationsKind === 'breaks-auth' || operationsKind === 'malformed') {
+		blockers.push('"operations" is not a list of operation names.');
+	}
+
+	for (const databaseName of getEditableDatabaseNames(instanceDatabaseMap, version)) {
+		if (!Object.hasOwn(permission, databaseName)) {
+			continue;
+		}
+		const record = permission[databaseName];
+		if (!isPlainRecord(record)) {
+			blockers.push(`The entry for database "${databaseName}" is not an object.`);
+			continue;
+		}
+		const tables = ownValue(record, 'tables');
+		if (tables === undefined) {
+			continue;
+		}
+		if (!isPlainRecord(tables)) {
+			blockers.push(`"${databaseName}.tables" is not an object.`);
+			continue;
+		}
+		for (const tableName of Object.keys(instanceDatabaseMap[databaseName])) {
+			const entry = ownValue(tables, tableName);
+			if (entry !== undefined) {
+				blockers.push(...getTableEntryBlockers(entry, `${databaseName}.${tableName}`));
+			}
+		}
+	}
+	return [...new Set(blockers)];
+}
+
+function getTableEntryBlockers(entry: unknown, label: string): string[] {
+	if (!isPlainRecord(entry)) {
+		return [`The entry for table "${label}" is not an object.`];
+	}
+	if (Object.hasOwn(entry, 'attribute_restrictions')) {
+		return [`"${label}" uses "attribute_restrictions", the role format from before Harper 2.2.`];
+	}
+	const blockers: string[] = [];
+	const nonBoolean = TABLE_ACTIONS.filter((action) => typeof entry[action] !== 'boolean');
+	if (nonBoolean.length) {
+		blockers.push(`"${label}": ${nonBoolean.join(', ')} must each be true or false.`);
+	}
+	const attributePermissions = ownValue(entry, 'attribute_permissions');
+	if (attributePermissions === null) {
+		return blockers;
+	}
+	if (!Array.isArray(attributePermissions)) {
+		blockers.push(`"${label}.attribute_permissions" must be a list.`);
+		return blockers;
+	}
+	const seen = new Set<string>();
+	for (const attributeEntry of attributePermissions) {
+		if (!isPlainRecord(attributeEntry) || typeof attributeEntry.attribute_name !== 'string') {
+			blockers.push(`"${label}.attribute_permissions" has an entry without an attribute_name.`);
+			continue;
+		}
+		const name = attributeEntry.attribute_name;
+		if (seen.has(name)) {
+			blockers.push(`"${label}.attribute_permissions" lists "${name}" more than once.`);
+		}
+		seen.add(name);
+		if (ATTRIBUTE_ACTIONS.some((action) => typeof attributeEntry[action] !== 'boolean')) {
+			blockers.push(`"${label}.attribute_permissions": "${name}" needs read, insert and update set to true or false.`);
+		}
+	}
+	return blockers;
+}
+
+function isLegacyRoleFormat(version: string): boolean {
+	// compareVersions orders an unparseable version below everything; only a real pre-2.2 is legacy.
+	return compareVersions(version, '0.0.0') >= 0 && compareVersions(version, '2.2.0') < 0;
+}
+
+export interface PreservedEntries {
+	/** Databases and tables the role names that this instance's describe_all does not list. */
+	notInSchema: string[];
+	/** Other content the GUI does not render; kept exactly as it is. */
+	notShown: string[];
+}
+
+/**
+ * What the document holds that the visual editor does not render. `notInSchema` is separated
+ * because Harper's role validation rejects a role naming a database or table that does not exist
+ * (`role_validation.ts` SCHEMA_NOT_FOUND / TABLE_NOT_FOUND), so those block a save until removed.
+ * Attribute entries the schema does not list are only "not shown": describe_all omits `@computed`
+ * attributes unless asked for them, so a missing name may well be a real attribute.
+ */
+export function getPreservedEntries(
+	permission: LocalRolePermission,
+	instanceDatabaseMap: InstanceDatabaseMap,
+	version: string,
+): PreservedEntries {
+	const allowlistSupported = supportsOperationsAllowlist(version);
+	const editable = new Set(getEditableDatabaseNames(instanceDatabaseMap, version));
+	const notInSchema: string[] = [];
+	const notShown: string[] = [];
+
+	if (Array.isArray(permission.structure_user)) {
+		for (const name of permission.structure_user) {
+			if (!editable.has(name)) {
+				notInSchema.push(`structure_user database "${name}"`);
+			}
+		}
+	}
+	if (
+		!allowlistSupported && permission.operations !== undefined
+		&& !getDatabaseKeys(permission, false).includes('operations')
+	) {
+		notShown.push('"operations" (has no effect before Harper 5.0)');
+	}
+
+	for (const databaseName of getDatabaseKeys(permission, allowlistSupported)) {
+		if (!editable.has(databaseName)) {
+			notInSchema.push(`database "${databaseName}"`);
+			continue;
+		}
+		const record = permission[databaseName];
+		if (!isPlainRecord(record)) {
+			continue;
+		}
+		for (const key of Object.keys(record)) {
+			if (key !== 'tables') {
+				notShown.push(`"${databaseName}.${key}"`);
+			}
+		}
+		const tables = ownValue(record, 'tables');
+		if (!isPlainRecord(tables)) {
+			continue;
+		}
+		const schemaTables = instanceDatabaseMap[databaseName];
+		for (const tableName of Object.keys(tables)) {
+			const schemaTable = Object.hasOwn(schemaTables, tableName) ? schemaTables[tableName] : undefined;
+			if (!schemaTable) {
+				notInSchema.push(`table "${databaseName}.${tableName}"`);
+				continue;
+			}
+			const entry = tables[tableName];
+			if (!isPlainRecord(entry)) {
+				continue;
+			}
+			const label = `${databaseName}.${tableName}`;
+			for (const key of Object.keys(entry)) {
+				if (!TABLE_ENTRY_KEYS.has(key)) {
+					notShown.push(`"${label}.${key}"`);
+				}
+			}
+			const attributePermissions = ownValue(entry, 'attribute_permissions');
+			if (!Array.isArray(attributePermissions)) {
+				continue;
+			}
+			const schemaAttributes = new Set(schemaTable.attributes.map((attribute) => attribute.attribute));
+			for (const attributeEntry of attributePermissions) {
+				if (!isPlainRecord(attributeEntry)) {
+					continue;
+				}
+				const name = String(attributeEntry.attribute_name);
+				if (!schemaAttributes.has(name)) {
+					notShown.push(`attribute "${label}.${name}"`);
+				}
+				for (const key of Object.keys(attributeEntry)) {
+					if (!ATTRIBUTE_ENTRY_KEYS.has(key)) {
+						notShown.push(`"${key}" on attribute "${label}.${name}"`);
+					}
+				}
+			}
+		}
+	}
+	return { notInSchema, notShown };
+}
+
+/**
+ * Removes exactly the `notInSchema` entries from getPreservedEntries: database keys and table keys
+ * the schema does not list, and structure_user names that are not databases here.
+ */
+export function removeEntriesNotInSchema(
+	permission: LocalRolePermission,
+	instanceDatabaseMap: InstanceDatabaseMap,
+	version: string,
+): LocalRolePermission {
+	const allowlistSupported = supportsOperationsAllowlist(version);
+	const editable = new Set(getEditableDatabaseNames(instanceDatabaseMap, version));
+	const missingDatabases = new Set(
+		getDatabaseKeys(permission, allowlistSupported).filter((name) => !editable.has(name)),
+	);
+	let next = withoutKeys(permission, missingDatabases);
+	if (Array.isArray(next.structure_user)) {
+		next = withKey(next, 'structure_user', next.structure_user.filter((name) => editable.has(name)));
+	}
+	for (const databaseName of editable) {
+		const record = ownValue(next, databaseName);
+		const tables = isPlainRecord(record) ? ownValue(record, 'tables') : undefined;
+		if (!isPlainRecord(record) || !isPlainRecord(tables)) {
+			continue;
+		}
+		const schemaTables = instanceDatabaseMap[databaseName];
+		const missingTables = new Set(Object.keys(tables).filter((name) => !Object.hasOwn(schemaTables, name)));
+		if (missingTables.size) {
+			next = withKey(next, databaseName, withKey(record, 'tables', withoutKeys(tables, missingTables)));
+		}
+	}
+	return next;
+}
+
+export function getRoleType(permission: LocalRolePermission): RoleType {
+	if (permission.super_user === true) {
+		return 'super_user';
+	}
+	return permission.cluster_user === true ? 'cluster_user' : 'standard';
+}
+
+/**
+ * Sets the exclusive role flag. A flag being turned off is written as `false` only where the key
+ * already exists, so a document that never carried it does not grow one. Everything else stays in
+ * the document until save, where preparePermissionForSave drops what Harper refuses alongside
+ * super_user/cluster_user — so flipping the type back within a session loses nothing.
+ */
+export function setRoleType(permission: LocalRolePermission, roleType: RoleType): LocalRolePermission {
+	let next = permission;
+	for (const flag of ['super_user', 'cluster_user'] as const) {
+		if (roleType === flag) {
+			next = withKey(next, flag, true);
+		} else if (Object.hasOwn(next, flag)) {
+			next = withKey(next, flag, false);
+		}
+	}
+	return orderPermissionKeys(next);
+}
+
+export function setStructureUser(permission: LocalRolePermission, value: boolean | string[]): LocalRolePermission {
+	if (value === false && !Object.hasOwn(permission, 'structure_user')) {
+		return permission;
+	}
+	return orderPermissionKeys(withKey(permission, 'structure_user', value));
+}
+
+/**
+ * The document's record for a database, typed loosely on purpose: it may carry keys beside
+ * `tables` (Harper's translator honours `describe`), and every one of them is carried over.
+ */
+export function getDatabaseRecord(permission: LocalRolePermission, databaseName: string): PlainRecord | undefined {
+	const record = ownValue(permission, databaseName);
+	return isPlainRecord(record) ? record : undefined;
+}
+
+/** A table entry within a database record, when it is in a shape the editor accepts. */
+export function getTableEntryInRecord(
+	record: PlainRecord | undefined,
+	tableName: string,
+): LocalRolePermissionTable | undefined {
+	const tables = record && ownValue(record, 'tables');
+	const entry = isPlainRecord(tables) ? ownValue(tables, tableName) : undefined;
+	return isPlainRecord(entry) ? entry as unknown as LocalRolePermissionTable : undefined;
+}
+
+export function getTableEntry(
+	permission: LocalRolePermission,
+	databaseName: string,
+	tableName: string,
+): LocalRolePermissionTable | undefined {
+	return getTableEntryInRecord(getDatabaseRecord(permission, databaseName), tableName);
+}
+
+export function isTableScopedToAttributes(entry: LocalRolePermissionTable | undefined): boolean {
+	// permissionsTranslator scopes only on a non-empty array; `[]` and `null` both mean "every attribute".
+	const attributePermissions = entry?.attribute_permissions;
+	return Array.isArray(attributePermissions) && attributePermissions.length > 0;
+}
+
+function newTableEntry(): LocalRolePermissionTable {
+	return { read: false, insert: false, update: false, delete: false, attribute_permissions: [] };
+}
+
+function withTableEntry(
+	permission: LocalRolePermission,
+	databaseName: string,
+	tableName: string,
+	entry: LocalRolePermissionTable,
+): LocalRolePermission {
+	const record = ownValue(permission, databaseName);
+	const base = isPlainRecord(record) ? record : {};
+	const tables = ownValue(base, 'tables');
+	const nextTables = withKey(isPlainRecord(tables) ? tables : {}, tableName, entry);
+	return withKey(permission, databaseName, withKey(base, 'tables', nextTables));
+}
+
+/**
+ * The entry with one table action set. Turning a read/insert/update off also turns it off on every
+ * attribute entry, because role validation rejects an attribute granting what its table does not
+ * (MISMATCHED_TABLE_ATTR_PERMS).
+ */
+function withTableAction(
+	entry: LocalRolePermissionTable,
+	action: LocalRolePermissionAction,
+	value: boolean,
+): LocalRolePermissionTable {
+	const next = { ...entry, [action]: value };
+	if (!value && action !== 'delete' && Array.isArray(entry.attribute_permissions)) {
+		next.attribute_permissions = entry.attribute_permissions.map((attribute) =>
+			attribute[action] ? { ...attribute, [action]: false } : attribute
+		);
+	}
+	return next;
+}
+
+export function setTableAction(
+	permission: LocalRolePermission,
+	databaseName: string,
+	tableName: string,
+	action: LocalRolePermissionAction,
+	value: boolean,
+): LocalRolePermission {
+	const entry = getTableEntry(permission, databaseName, tableName);
+	if (!entry && !value) {
+		// A table the role does not mention already has no access (permissionsTranslator).
+		return permission;
+	}
+	return withTableEntry(permission, databaseName, tableName, withTableAction(entry ?? newTableEntry(), action, value));
+}
+
+/** Sets one action on every listed table of a database in a single rebuild. */
+export function setDatabaseAction(
+	permission: LocalRolePermission,
+	databaseName: string,
+	tableNames: string[],
+	action: LocalRolePermissionAction,
+	value: boolean,
+): LocalRolePermission {
+	const record = ownValue(permission, databaseName);
+	const base = isPlainRecord(record) ? record : {};
+	const tables = ownValue(base, 'tables');
+	const existing = isPlainRecord(tables) ? tables : {};
+	const pending = new Map<string, LocalRolePermissionTable>();
+	for (const tableName of tableNames) {
+		const entry = getTableEntry(permission, databaseName, tableName);
+		if (entry || value) {
+			pending.set(tableName, withTableAction(entry ?? newTableEntry(), action, value));
+		}
+	}
+	if (!pending.size) {
+		return permission;
+	}
+	const entries = Object.entries(existing).map(([name, entry]): [string, unknown] => {
+		const replacement = pending.get(name);
+		pending.delete(name);
+		return [name, replacement ?? entry];
+	});
+	entries.push(...pending.entries());
+	return withKey(permission, databaseName, withKey(base, 'tables', Object.fromEntries(entries)));
+}
+
+export interface AttributeView {
+	name: string;
+	read: boolean;
+	insert: boolean;
+	update: boolean;
+	isPrimaryKey: boolean;
+	/** Only read applies (permissionsTranslator replaces the entry with a read-only one). */
+	isTimestamp: boolean;
+	/** An unlisted primary key, whose access Harper derives from the listed attributes. */
+	derived: boolean;
+}
+
+/**
+ * Effective attribute access for a scoped table, as permissionsTranslator's getTableAttrPerms
+ * computes it: listed attributes as listed, unlisted ones get nothing, except an unlisted primary
+ * key, which gets each action any listed attribute has.
+ */
+export function getAttributeViews(
+	entry: LocalRolePermissionTable,
+	attributeNames: string[],
+	primaryKey: string | undefined,
+): AttributeView[] {
+	const listed = new Map(
+		(entry.attribute_permissions ?? []).map((attribute) => [attribute.attribute_name, attribute]),
+	);
+	const effective = (name: string, attribute: LocalRoleAttributePermissionTable | undefined) => {
+		const timestamp = TIMESTAMP_ATTRIBUTES.has(name);
+		return {
+			read: attribute?.read === true,
+			insert: !timestamp && attribute?.insert === true,
+			update: !timestamp && attribute?.update === true,
+		};
+	};
+	const derivedPrimaryKey = { read: false, insert: false, update: false };
+	for (const name of attributeNames) {
+		const attribute = listed.get(name);
+		if (name !== primaryKey && attribute) {
+			const access = effective(name, attribute);
+			for (const action of ATTRIBUTE_ACTIONS) {
+				derivedPrimaryKey[action] ||= access[action];
+			}
+		}
+	}
+	return attributeNames.map((name) => {
+		const attribute = listed.get(name);
+		const isPrimaryKey = name === primaryKey;
+		const derived = isPrimaryKey && !attribute;
+		return {
+			name,
+			...(derived ? derivedPrimaryKey : effective(name, attribute)),
+			isPrimaryKey,
+			isTimestamp: TIMESTAMP_ATTRIBUTES.has(name),
+			derived,
+		};
+	});
+}
+
+/**
+ * Turns attribute scoping on or off for one table. Turning it on lists every attribute with the
+ * table's own read/insert/update, so the role's current access does not change at the moment of
+ * switching — only attributes added to the table later stay unreadable until granted. Turning it
+ * off writes `[]`; `restore` brings back a list the author turned off this session, less any action
+ * the table has lost since, which role validation would reject on the attribute.
+ */
+export function setAttributeScoping(
+	permission: LocalRolePermission,
+	databaseName: string,
+	tableName: string,
+	scoped: boolean,
+	attributeNames: string[],
+	restore?: LocalRoleAttributePermissionTable[],
+): LocalRolePermission {
+	const entry = getTableEntry(permission, databaseName, tableName) ?? newTableEntry();
+	const attributePermissions = scoped
+		? restore?.length
+			? restore.map((attribute) => ({
+				...attribute,
+				read: attribute.read && entry.read,
+				insert: attribute.insert && entry.insert,
+				update: attribute.update && entry.update,
+			}))
+			: attributeNames.map((name) => ({
+				attribute_name: name,
+				read: entry.read,
+				insert: TIMESTAMP_ATTRIBUTES.has(name) ? false : entry.insert,
+				update: TIMESTAMP_ATTRIBUTES.has(name) ? false : entry.update,
+			}))
+		: [];
+	return withTableEntry(permission, databaseName, tableName, { ...entry, attribute_permissions: attributePermissions });
+}
+
+/**
+ * Sets one action on one attribute of a scoped table. An unlisted attribute is added with its
+ * effective access first (so a derived primary key keeps what it had), and granting an action the
+ * table lacks also grants it on the table, which role validation requires.
+ */
+export function setAttributeAction(
+	permission: LocalRolePermission,
+	databaseName: string,
+	tableName: string,
+	attributeNames: string[],
+	primaryKey: string | undefined,
+	attributeName: string,
+	action: LocalRoleAttributePermissionAction,
+	value: boolean,
+): LocalRolePermission {
+	const entry = getTableEntry(permission, databaseName, tableName);
+	if (!entry || !Array.isArray(entry.attribute_permissions)) {
+		return permission;
+	}
+	const list = entry.attribute_permissions;
+	const index = list.findIndex((attribute) => attribute.attribute_name === attributeName);
+	let nextList: LocalRoleAttributePermissionTable[];
+	if (index >= 0) {
+		nextList = list.map((attribute, position) => position === index ? { ...attribute, [action]: value } : attribute);
+	} else {
+		const view = getAttributeViews(entry, attributeNames, primaryKey).find((item) => item.name === attributeName);
+		nextList = [...list, {
+			attribute_name: attributeName,
+			read: view?.read ?? false,
+			insert: view?.insert ?? false,
+			update: view?.update ?? false,
+			[action]: value,
+		}];
+	}
+	const nextEntry = {
+		...entry,
+		attribute_permissions: nextList,
+		...(value && !entry[action] ? { [action]: true } : {}),
+	};
+	return withTableEntry(permission, databaseName, tableName, nextEntry);
+}
diff --git a/src/features/instance/config/roles/editor/useRolePermissionDraft.ts b/src/features/instance/config/roles/editor/useRolePermissionDraft.ts
new file mode 100644
index 000000000..4faad7eb2
--- /dev/null
+++ b/src/features/instance/config/roles/editor/useRolePermissionDraft.ts
@@ -0,0 +1,32 @@
+import {
+	parseRolePermissionText,
+	serializeRolePermission,
+} from '@/features/instance/config/roles/editor/rolePermissionModel';
+import { LocalRolePermission } from '@/integrations/api/api.patch';
+import { orderPermissionKeys } from '@/integrations/api/localRolePermission';
+import { useCallback, useState } from 'react';
+
+export interface RolePermissionDraft {
+	/** The source of truth, as the JSON view shows it. */
+	text: string;
+	/** `text` parsed, or null while it isn't a JSON object. */
+	permission: LocalRolePermission | null;
+	setText: (text: string) => void;
+	setPermission: (permission: LocalRolePermission) => void;
+}
+
+/**
+ * The role editor's draft. A visual edit keeps the document it produced instead of re-parsing the
+ * text it serializes to, so every database and table the edit did not touch keeps its object
+ * identity — which is what lets the editor skip re-rendering them on a large schema.
+ */
+export function useRolePermissionDraft(initial: LocalRolePermission): RolePermissionDraft {
+	const [draft, setDraft] = useState<Pick<RolePermissionDraft, 'text' | 'permission'>>(() => fromPermission(initial));
+	const setText = useCallback((text: string) => setDraft({ text, permission: parseRolePermissionText(text) }), []);
+	const setPermission = useCallback((permission: LocalRolePermission) => setDraft(fromPermission(permission)), []);
+	return { ...draft, setText, setPermission };
+}
+
+function fromPermission(permission: LocalRolePermission) {
+	return { text: serializeRolePermission(permission), permission: orderPermissionKeys(permission) };
+}
diff --git a/src/features/instance/config/roles/index.tsx b/src/features/instance/config/roles/index.tsx
index 0272a61f5..f45eedf2d 100644
--- a/src/features/instance/config/roles/index.tsx
+++ b/src/features/instance/config/roles/index.tsx
@@ -47,11 +47,13 @@ export function ConfigRolesIndex() {
 	const onAddClicked = useCallback(() => {
 		setIsAddModalOpen(true);
 	}, [setIsAddModalOpen]);
-	const onRoleAdded = useCallback((newRoleId: string) => {
+	const onRoleAdded = useCallback(() => {
 		void refetch();
 		setIsAddModalOpen(false);
-		onSelectRole(newRoleId);
-	}, [onSelectRole, refetch]);
+	}, [refetch]);
+	const closeAddModal = useCallback(() => {
+		setIsAddModalOpen(false);
+	}, []);
 
 	const onRowClick = useCallback(
 		(rowData: Row<LocalRole>) => {
@@ -88,7 +90,7 @@ export function ConfigRolesIndex() {
 					</Button>
 				</SimpleBrowseDataTable>
 			</AllowlistSupportedProvider>
-			<AddRoleModal isModalOpen={isAddModalOpen} onChangesSaved={onRoleAdded} setIsModalOpen={setIsAddModalOpen} />
+			{isAddModalOpen && <AddRoleModal onChangesSaved={onRoleAdded} closeModal={closeAddModal} />}
 			{isEditModalOpen && (
 				<EditRoleModal
 					instanceId={instanceId}
diff --git a/src/features/instance/config/roles/modals/AddRoleModal.test.tsx b/src/features/instance/config/roles/modals/AddRoleModal.test.tsx
new file mode 100644
index 000000000..59f0b46ee
--- /dev/null
+++ b/src/features/instance/config/roles/modals/AddRoleModal.test.tsx
@@ -0,0 +1,99 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { AddRoleModal } from '@/features/instance/config/roles/modals/AddRoleModal';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+const { addRoleMutate } = vi.hoisted(() => ({ addRoleMutate: vi.fn() }));
+
+vi.mock('@/lib/monaco/MonacoEditor', () => ({
+	Editor: ({ value, onChange }: { value?: string; onChange?: (next: string) => void }) => (
+		<textarea
+			aria-label="Role permission JSON"
+			value={value ?? ''}
+			onChange={(e) => onChange?.(e.target.value)}
+		/>
+	),
+}));
+vi.mock('@/hooks/useMonacoTheme', () => ({ useMonacoTheme: () => 'vs-dark' }));
+vi.mock('@/config/useInstanceClient', () => ({ useInstanceClientIdParams: () => ({}) }));
+vi.mock('@/integrations/api/instance/auth/addRole', () => ({
+	useAddRoleMutation: () => ({ mutate: addRoleMutate, isPending: false }),
+}));
+vi.mock('@/integrations/api/instance/database/getDescribeAll', () => ({
+	getDescribeAllQueryOptions: () => ({
+		queryKey: ['test', 'describe_all'],
+		queryFn: () => ({ data: { dog: { primary_key: 'id', attributes: [{ attribute: 'id' }] } } }),
+	}),
+}));
+vi.mock('@/integrations/api/instance/status/getRegistrationInfo', () => ({
+	getRegistrationInfoQueryOptions: () => ({
+		queryKey: ['test', 'registration_info'],
+		queryFn: () => ({ version: '5.3.1' }),
+	}),
+}));
+
+beforeAll(() => {
+	Element.prototype.hasPointerCapture ??= () => false;
+	Element.prototype.setPointerCapture ??= () => undefined;
+	Element.prototype.releasePointerCapture ??= () => undefined;
+	Element.prototype.scrollIntoView ??= () => undefined;
+	if (typeof window.PointerEvent === 'undefined') {
+		window.PointerEvent = class extends MouseEvent {} as typeof PointerEvent;
+	}
+});
+
+afterEach(() => {
+	cleanup();
+	addRoleMutate.mockClear();
+});
+
+function renderModal() {
+	const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+	render(
+		<QueryClientProvider client={queryClient}>
+			<AddRoleModal onChangesSaved={() => {}} closeModal={() => {}} />
+		</QueryClientProvider>,
+	);
+}
+
+async function submitAs(name: string) {
+	fireEvent.change(screen.getByRole('textbox', { name: 'Name' }), { target: { value: name } });
+	fireEvent.click(screen.getByRole('button', { name: /Add Role/ }));
+	await waitFor(() => expect(addRoleMutate).toHaveBeenCalledTimes(1));
+	const [payload] = addRoleMutate.mock.calls[0];
+	expect(payload.role).toBe(name);
+	return payload.permission as Record<string, unknown>;
+}
+
+describe('AddRoleModal', () => {
+	it('creates a role with its table permissions in one step', async () => {
+		renderModal();
+
+		fireEvent.click(await screen.findByRole('checkbox', { name: 'Read on data.dog' }));
+		expect(await submitAs('readers')).toEqual({
+			super_user: false,
+			structure_user: false,
+			data: {
+				tables: { dog: { read: true, insert: false, update: false, delete: false, attribute_permissions: [] } },
+			},
+		});
+	});
+
+	it('creates a super user role with nothing beside the flag, which is all Harper accepts', async () => {
+		renderModal();
+
+		fireEvent.click(await screen.findByRole('radio', { name: /Super user/ }));
+		// The old form always sent `structure_user` too, which Harper rejects beside super_user: true.
+		expect(await submitAs('admins')).toEqual({ super_user: true });
+	});
+
+	it('does not offer the cluster user type on Harper 5', async () => {
+		renderModal();
+
+		await screen.findByRole('radio', { name: /Super user/ });
+		expect(screen.queryByRole('radio', { name: /Cluster user/ })).toBeNull();
+	});
+});
diff --git a/src/features/instance/config/roles/modals/AddRoleModal.tsx b/src/features/instance/config/roles/modals/AddRoleModal.tsx
index 744d401c0..6e5167aa9 100644
--- a/src/features/instance/config/roles/modals/AddRoleModal.tsx
+++ b/src/features/instance/config/roles/modals/AddRoleModal.tsx
@@ -15,6 +15,13 @@ import { FormLabel } from '@/components/ui/form/FormLabel';
 import { FormMessage } from '@/components/ui/form/FormMessage';
 import { Input } from '@/components/ui/input';
 import { useInstanceClientIdParams } from '@/config/useInstanceClient';
+import {
+	isOperationsValueUnusable,
+	RolePermissionEditor,
+	useRoleEditorSchema,
+} from '@/features/instance/config/roles/editor/RolePermissionEditor';
+import { useRolePermissionDraft } from '@/features/instance/config/roles/editor/useRolePermissionDraft';
+import { preparePermissionForSave } from '@/features/instance/config/roles/preparePermissionForSave';
 import { AddRoleFormData, useAddRoleMutation } from '@/integrations/api/instance/auth/addRole';
 import { AddRoleFormSchema } from '@/integrations/api/instance/auth/addRoleFormSchema';
 import { zodResolver } from '@hookform/resolvers/zod';
@@ -23,77 +30,74 @@ import { useCallback } from 'react';
 import { useForm } from 'react-hook-form';
 import { toast } from 'sonner';
 
+/** The shape add_role has always been sent for a new, not-yet-granted role. */
+const NEW_ROLE_PERMISSION = { super_user: false, structure_user: false };
+
+/**
+ * Creates a role with its full permissions in one step, through the same editor as editing one.
+ * Render it only while open: its draft lives in this component's state.
+ */
 export function AddRoleModal({
-	isModalOpen,
 	onChangesSaved,
-	setIsModalOpen,
+	closeModal,
 }: {
-	isModalOpen: boolean;
-	onChangesSaved: (roleId: string) => void;
-	setIsModalOpen: (open: boolean) => void;
+	onChangesSaved: () => void;
+	closeModal: () => void;
 }) {
 	const form = useForm({
 		resolver: zodResolver(AddRoleFormSchema),
-		defaultValues: {
-			role: '',
-			super_user: false,
-			structure_user: false,
-		},
+		defaultValues: { role: '' },
 	});
 	const instanceParams = useInstanceClientIdParams();
+	const schema = useRoleEditorSchema();
 	const { mutate: addRole, isPending: isAddPending } = useAddRoleMutation();
+	const draft = useRolePermissionDraft(NEW_ROLE_PERMISSION);
+	const { permission } = draft;
+	const operationsUnusable = isOperationsValueUnusable(permission, schema.version);
 
 	const onSubmitClick = useCallback(
-		async (formData: AddRoleFormData) => {
-			if (formData) {
-				addRole(
-					{
-						role: formData.role,
-						super_user: formData.super_user,
-						structure_user: formData.structure_user,
-						...instanceParams,
-					},
-					{
-						onSuccess: (newRole) => {
-							form.reset();
-							onChangesSaved(newRole.id);
-							toast.success('Role added successfully!');
-							setIsModalOpen(false);
-						},
-					},
-				);
+		(formData: AddRoleFormData) => {
+			if (!permission || operationsUnusable) {
+				return;
 			}
+			addRole(
+				{
+					role: formData.role,
+					// Also what lets a super user role be created at all: Harper rejects one that carries any
+					// other key, including the `structure_user: false` a new role starts with.
+					permission: preparePermissionForSave(permission),
+					...instanceParams,
+				},
+				{
+					onSuccess: () => {
+						toast.success('Role added successfully!');
+						onChangesSaved();
+					},
+				},
+			);
 		},
-		[addRole, form, instanceParams, onChangesSaved, setIsModalOpen],
+		[addRole, instanceParams, onChangesSaved, operationsUnusable, permission],
 	);
 
-	const onClickCancel = useCallback(() => {
-		form.reset();
-		setIsModalOpen(false);
-	}, [form, setIsModalOpen]);
-
 	return (
-		<Dialog onOpenChange={setIsModalOpen} open={isModalOpen}>
-			{/* NOTE - Is this okay to do for the aria describedby? */}
-			<DialogContent aria-describedby={undefined}>
+		<Dialog onOpenChange={closeModal} open>
+			<DialogContent resizable aria-describedby={undefined}>
 				<Form {...form}>
 					<form
 						id="instance-add-role-form"
 						name="instance-add-role-form"
 						onSubmit={form.handleSubmit(onSubmitClick)}
-						className="grid gap-4 my-4 md:grid-cols-2"
+						className="flex min-h-0 flex-1 flex-col gap-4"
 					>
-						<DialogHeader className="md:col-span-2">
+						<DialogHeader>
 							<DialogTitle>Add New Role</DialogTitle>
-							<DialogDescription>
-								After adding the role, you will be able to edit the per-table permissions.
-							</DialogDescription>
+							<DialogDescription>Name the role and choose what it can access.</DialogDescription>
 						</DialogHeader>
 						<FormField
 							control={form.control}
 							name="role"
 							render={({ field }) => (
-								<FormItem className="md:col-span-2">
+								<FormItem>
 									<FormLabel className="pb-1">Name</FormLabel>
 									<FormControl>
 										<Input type="text" {...field} />
@@ -102,54 +106,22 @@ export function AddRoleModal({
 								</FormItem>
 							)}
 						/>
-						<FormField
-							control={form.control}
-							name="super_user"
-							render={({ field }) => (
-								<FormItem className="flex">
-									<FormControl>
-										<Input
-											type="checkbox"
-											className="w-6"
-											checked={field.value}
-											onChange={(e) => field.onChange(e.target.checked)}
-										/>
-									</FormControl>
-									<FormLabel className="pl-4 pr-8 flex-1 py-2.5">Super User</FormLabel>
-									<FormMessage />
-								</FormItem>
-							)}
-						/>
-						<FormField
-							control={form.control}
-							name="structure_user"
-							render={({ field }) => (
-								<FormItem className="flex">
-									<FormControl>
-										<Input
-											type="checkbox"
-											className="w-6"
-											checked={field.value}
-											onChange={(e) => field.onChange(e.target.checked)}
-										/>
-									</FormControl>
-									<FormLabel className="pl-4 pr-8 flex-1 py-2.5">Structure User</FormLabel>
-									<FormMessage />
-								</FormItem>
-							)}
-						/>
-
-						<DialogFooter className="md:col-span-2">
+						<RolePermissionEditor draft={draft} schema={schema} />
+						<DialogFooter>
 							<div className="flex justify-between w-full">
 								<Button
 									variant="destructiveOutline"
 									type="button"
-									onClick={onClickCancel}
+									onClick={closeModal}
 									disabled={isAddPending}
 								>
 									Cancel
 								</Button>
-								<Button type="submit" variant="submit" disabled={isAddPending}>
+								<Button
+									type="submit"
+									variant="submit"
+									disabled={isAddPending || !permission || operationsUnusable}
+								>
 									<Save /> Add Role
 								</Button>
 							</div>
diff --git a/src/features/instance/config/roles/modals/EditRoleModal.test.tsx b/src/features/instance/config/roles/modals/EditRoleModal.test.tsx
index 82237205c..53453b9df 100644
--- a/src/features/instance/config/roles/modals/EditRoleModal.test.tsx
+++ b/src/features/instance/config/roles/modals/EditRoleModal.test.tsx
@@ -2,18 +2,22 @@
  * @vitest-environment jsdom
  */
 import { EditRoleModal } from '@/features/instance/config/roles/modals/EditRoleModal';
-import { LocalRole } from '@/integrations/api/api.patch';
+import { InstanceDatabaseMap, LocalRole } from '@/integrations/api/api.patch';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { cleanup, fireEvent, render, screen } from '@testing-library/react';
-import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 
 /*
- Exercises the full operations-lens wiring the component tests can't: a picker interaction must
- land in the JSON text (with `operations` ordered right after the top-level flags), and Save must
- send preparePermissionForSave's exact permission payload through alter_role.
+ Exercises the modal end to end: the visual editor and the JSON view share one draft, and Save
+ sends preparePermissionForSave's exact permission payload through alter_role.
  */
 
-const { alterRoleMutate } = vi.hoisted(() => ({ alterRoleMutate: vi.fn() }));
+const mocks = vi.hoisted(() => ({
+	alterRoleMutate: vi.fn(),
+	schema: {} as InstanceDatabaseMap,
+	describeAllFails: false,
+	selfRoleId: 'someone-elses-role',
+}));
 
 // A controlled stand-in with the same contract as the Monaco wrapper: renders `value`, reports
 // edits through onChange. Monaco itself cannot finish loading under jsdom.
@@ -29,10 +33,10 @@ vi.mock('@/lib/monaco/MonacoEditor', () => ({
 vi.mock('@/hooks/useMonacoTheme', () => ({ useMonacoTheme: () => 'vs-dark' }));
 vi.mock('@/config/useInstanceClient', () => ({ useInstanceClientIdParams: () => ({}) }));
 vi.mock('@/hooks/useAuth', () => ({
-	useInstanceAuth: () => ({ user: { role: { id: 'someone-elses-role' } } }),
+	useInstanceAuth: () => ({ user: { role: { id: mocks.selfRoleId } } }),
 }));
 vi.mock('@/integrations/api/instance/auth/alterRole', () => ({
-	useAlterRole: () => ({ mutate: alterRoleMutate, isPending: false }),
+	useAlterRole: () => ({ mutate: mocks.alterRoleMutate, isPending: false }),
 }));
 vi.mock('@/integrations/api/instance/auth/deleteRole', () => ({
 	useDeleteRoleMutation: () => ({ mutate: vi.fn(), isPending: false }),
@@ -40,7 +44,13 @@ vi.mock('@/integrations/api/instance/auth/deleteRole', () => ({
 vi.mock('@/integrations/api/instance/database/getDescribeAll', () => ({
 	getDescribeAllQueryOptions: () => ({
 		queryKey: ['test', 'describe_all'],
-		queryFn: () => ({ data: { dog: { attributes: [{ attribute: 'id' }] } } }),
+		queryFn: () => {
+			if (mocks.describeAllFails) {
+				throw new Error('describe_all failed');
+			}
+			return mocks.schema;
+		},
+		retry: false,
 	}),
 }));
 vi.mock('@/integrations/api/instance/status/getRegistrationInfo', () => ({
@@ -50,6 +60,17 @@ vi.mock('@/integrations/api/instance/status/getRegistrationInfo', () => ({
 	}),
 }));
 
+const dogSchema = {
+	data: {
+		dog: {
+			name: 'dog',
+			schema: 'data',
+			primary_key: 'id',
+			attributes: [{ attribute: 'id', is_primary_key: true }, { attribute: 'name' }],
+		},
+	},
+} as unknown as InstanceDatabaseMap;
+
 // Radix's switch/dialog rely on DOM APIs jsdom doesn't implement.
 beforeAll(() => {
 	Element.prototype.hasPointerCapture ??= () => false;
@@ -61,54 +82,241 @@ beforeAll(() => {
 	}
 });
 
+beforeEach(() => {
+	mocks.schema = dogSchema;
+	mocks.describeAllFails = false;
+	mocks.selfRoleId = 'someone-elses-role';
+});
+
 afterEach(() => {
 	cleanup();
-	alterRoleMutate.mockClear();
+	mocks.alterRoleMutate.mockClear();
 });
 
-function renderModal(permission: LocalRole['permission']) {
-	const data: LocalRole = {
+function roleData(permission: unknown, updatedTime = 0): LocalRole {
+	return {
 		id: 'role-1',
 		role: 'test_role',
-		permission,
+		permission: permission as LocalRole['permission'],
 		__createdtime__: 0,
-		__updatedtime__: 0,
+		__updatedtime__: updatedTime,
 	};
-	const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
-	return render(
-		<QueryClientProvider client={queryClient}>
-			<EditRoleModal
-				data={data}
-				isModalOpen
-				closeModal={() => {}}
-				onSelectRole={() => {}}
-				onChangesSaved={() => {}}
-			/>
-		</QueryClientProvider>,
+}
+
+function modal(data: LocalRole) {
+	return (
+		<EditRoleModal
+			data={data}
+			isModalOpen
+			closeModal={() => {}}
+			onSelectRole={() => {}}
+			onChangesSaved={() => {}}
+		/>
 	);
 }
 
+function renderModal(permission: unknown) {
+	const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+	const result = render(<QueryClientProvider client={queryClient}>{modal(roleData(permission))}</QueryClientProvider>);
+	return {
+		...result,
+		rerenderWith: (data: LocalRole) =>
+			result.rerender(<QueryClientProvider client={queryClient}>{modal(data)}</QueryClientProvider>),
+	};
+}
+
+function save() {
+	fireEvent.click(screen.getByRole('button', { name: 'Save Changes' }));
+	expect(mocks.alterRoleMutate).toHaveBeenCalledTimes(1);
+	const [payload] = mocks.alterRoleMutate.mock.calls[0];
+	expect(payload.id).toBe('role-1');
+	return payload.permission as Record<string, unknown>;
+}
+
+function jsonEditor() {
+	fireEvent.click(screen.getByRole('button', { name: 'Edit as JSON' }));
+	return screen.getByRole('textbox', { name: 'Role permission JSON' }) as HTMLTextAreaElement;
+}
+
+const readOnlyDog = (attributePermissions: unknown, extra: object = {}) => ({
+	tables: {
+		dog: {
+			read: true,
+			insert: false,
+			update: false,
+			delete: false,
+			attribute_permissions: attributePermissions,
+			...extra,
+		},
+	},
+});
+
+describe('EditRoleModal visual editor', () => {
+	it('opens on the visual editor and saves a table grant with an empty attribute_permissions array', async () => {
+		// The shape AddRoleModal has always created before any table is granted.
+		renderModal({ super_user: false, structure_user: false });
+
+		fireEvent.click(await screen.findByRole('checkbox', { name: 'Read on data.dog' }));
+		// A null here makes every `['*']` read the role sends 500 (#1299, HarperFast/harper#3143).
+		expect(save()).toEqual({ super_user: false, structure_user: false, data: readOnlyDog([]) });
+	});
+
+	it('repairs a role already stored with null when it is saved again', async () => {
+		renderModal({ super_user: false, data: readOnlyDog(null) });
+
+		expect((await screen.findByRole('checkbox', { name: 'Read on data.dog' }) as HTMLInputElement).checked).toBe(
+			true,
+		);
+		expect(save()).toEqual({ super_user: false, data: readOnlyDog([]) });
+	});
+
+	it('keeps content the GUI does not model through an edit', async () => {
+		renderModal({ data: { describe: true, ...readOnlyDog([], { note: 'kept' }) }, gone: { tables: {} } });
+
+		expect(await screen.findByText(/Also kept as they are/)).toBeTruthy();
+		fireEvent.click(screen.getByRole('checkbox', { name: 'Insert on data.dog' }));
+		const permission = save();
+		expect(permission.data).toEqual({
+			describe: true,
+			tables: {
+				dog: { read: true, insert: true, update: false, delete: false, attribute_permissions: [], note: 'kept' },
+			},
+		});
+		// Not in the schema, but the GUI never deletes it on its own.
+		expect(permission.gone).toEqual({ tables: {} });
+	});
+
+	it('removes databases and tables the schema lacks only when asked, since Harper rejects them', async () => {
+		renderModal({ data: { tables: { dog: readOnlyDog([]).tables.dog, removed_table: {} } }, gone: { tables: {} } });
+
+		expect(await screen.findByText(/table "data.removed_table", database "gone"/)).toBeTruthy();
+		fireEvent.click(screen.getByRole('button', { name: 'Remove them' }));
+		expect(save()).toEqual({ data: readOnlyDog([]) });
+	});
+
+	it('scopes a table to attributes and saves the per-attribute grants', async () => {
+		renderModal({ data: readOnlyDog([]) });
+
+		fireEvent.click(await screen.findByRole('button', { name: 'Attribute permissions for data.dog' }));
+		fireEvent.click(screen.getByRole('switch', { name: 'Limit data.dog to specific attributes' }));
+		fireEvent.click(screen.getByRole('checkbox', { name: 'Read on data.dog.name' }));
+		expect(save()).toEqual({
+			data: readOnlyDog([
+				{ attribute_name: 'id', read: true, insert: false, update: false },
+				{ attribute_name: 'name', read: false, insert: false, update: false },
+			]),
+		});
+	});
+
+	it('shares one draft between the visual editor and the JSON view', async () => {
+		renderModal({ super_user: false });
+
+		fireEvent.click(await screen.findByRole('checkbox', { name: 'Read on data.dog' }));
+		const editor = jsonEditor();
+		const document = JSON.parse(editor.value) as { data: { tables: { dog: { delete: boolean } } } };
+		expect(document.data.tables.dog).toEqual(readOnlyDog([]).tables.dog);
+		document.data.tables.dog.delete = true;
+		fireEvent.change(editor, { target: { value: JSON.stringify(document, null, 2) } });
+
+		fireEvent.click(screen.getByRole('button', { name: /Visual editor/ }));
+		expect((screen.getByRole('checkbox', { name: 'Delete on data.dog' }) as HTMLInputElement).checked).toBe(true);
+		expect(save()).toEqual({ super_user: false, data: { tables: { dog: { ...document.data.tables.dog } } } });
+	});
+
+	it('keeps the JSON view in charge, and says why, while the document is not representable', async () => {
+		renderModal({ data: readOnlyDog([]) });
+
+		await screen.findByRole('button', { name: 'Edit as JSON' });
+		const editor = jsonEditor();
+		fireEvent.change(editor, { target: { value: '{"data": ' } });
+		expect(screen.getByText('The JSON is not a valid object.')).toBeTruthy();
+		expect(screen.getByRole('button', { name: /Visual editor/ }).hasAttribute('disabled')).toBe(true);
+		expect(screen.getByRole('button', { name: 'Save Changes' }).hasAttribute('disabled')).toBe(true);
+
+		fireEvent.change(editor, { target: { value: '{"data": {"tables": {"dog": {"read": "yes"}}}}' } });
+		expect(screen.getByText(/"data.dog": read, insert, update, delete must each be true or false/)).toBeTruthy();
+		expect(screen.getByRole('button', { name: /Visual editor/ }).hasAttribute('disabled')).toBe(true);
+	});
+
+	it('opens a role the GUI cannot represent straight into the JSON view', async () => {
+		renderModal({ data: { tables: { dog: { read: 1 } } } });
+
+		expect(await screen.findByRole('textbox', { name: 'Role permission JSON' })).toBeTruthy();
+		expect(screen.queryByRole('checkbox', { name: 'Read on data.dog' })).toBeNull();
+	});
+
+	it('hides per-table permissions for a structure user of every database and drops them on save', async () => {
+		renderModal({ data: readOnlyDog([]) });
+
+		fireEvent.click(await screen.findByRole('radio', { name: /All databases/ }));
+		expect(screen.queryByRole('checkbox', { name: 'Read on data.dog' })).toBeNull();
+		expect(screen.getByText(/Per-table permissions don't apply to this role/)).toBeTruthy();
+		expect(save()).toEqual({ structure_user: true });
+	});
+
+	it('saves a super user role with nothing beside the flag', async () => {
+		renderModal({ structure_user: ['data'], data: readOnlyDog([]) });
+
+		fireEvent.click(await screen.findByRole('radio', { name: /Super user/ }));
+		expect(screen.getByText(/Saving keeps only the/)).toBeTruthy();
+		// validateNoSUPerms rejects super_user beside any other key, structure_user included.
+		expect(save()).toEqual({ super_user: true });
+	});
+
+	it("is read-only on the editor's own role", async () => {
+		mocks.selfRoleId = 'role-1';
+		renderModal({ data: readOnlyDog([]) });
+
+		const read = await screen.findByRole('checkbox', { name: 'Read on data.dog' });
+		expect(read.hasAttribute('disabled')).toBe(true);
+		expect(screen.queryByRole('button', { name: 'Save Changes' })).toBeNull();
+	});
+
+	it('falls back to the JSON view, still saveable, when the schema does not load', async () => {
+		mocks.describeAllFails = true;
+		renderModal({ data: readOnlyDog([]) });
+
+		expect(await screen.findByRole('button', { name: /Retry/ })).toBeTruthy();
+		expect(screen.queryByRole('button', { name: /Visual editor/ })).toBeNull();
+		expect(save()).toEqual({ data: readOnlyDog([]) });
+	});
+
+	it('warns when the role changes elsewhere while open, and can load that version', async () => {
+		const { rerenderWith } = renderModal({ data: readOnlyDog([]) });
+		fireEvent.click(await screen.findByRole('checkbox', { name: 'Insert on data.dog' }));
+
+		// A list refetch with the same role must not touch the draft…
+		rerenderWith(roleData({ data: readOnlyDog([]) }));
+		expect(screen.queryByText(/changed somewhere else/)).toBeNull();
+		expect((screen.getByRole('checkbox', { name: 'Insert on data.dog' }) as HTMLInputElement).checked).toBe(true);
+
+		// …while a newer stored version is announced rather than silently overwritten.
+		rerenderWith(roleData({ super_user: true }, 5));
+		expect(screen.getByText(/changed somewhere else/)).toBeTruthy();
+		fireEvent.click(screen.getByRole('button', { name: 'Load the latest version' }));
+		expect(screen.queryByText(/changed somewhere else/)).toBeNull();
+		expect((screen.getByRole('radio', { name: /Super user/ }) as HTMLButtonElement).getAttribute('aria-checked')).toBe(
+			'true',
+		);
+	});
+});
+
 describe('EditRoleModal operations wiring', () => {
 	it('writes picker changes into the JSON with operations at the top, and saves that payload', async () => {
 		renderModal({});
 
-		fireEvent.click(await screen.findByRole('switch', { name: 'Restrict operations' }));
+		fireEvent.click(await screen.findByRole('checkbox', { name: 'Read on data.dog' }));
+		fireEvent.click(screen.getByRole('switch', { name: 'Restrict operations' }));
 		fireEvent.click(screen.getByRole('checkbox', { name: /^read_only/ }));
 
-		const editor = screen.getByRole('textbox', { name: 'Role permission JSON' }) as HTMLTextAreaElement;
-		const written = JSON.parse(editor.value) as Record<string, unknown>;
+		const written = JSON.parse(jsonEditor().value) as Record<string, unknown>;
 		expect(written.operations).toEqual(['read_only']);
-		// The allowlist must sit above the seeded table permissions, not below them.
+		// The allowlist must sit above the table permissions, not below them.
 		expect(Object.keys(written).indexOf('operations')).toBeLessThan(Object.keys(written).indexOf('data'));
-		// The database seeded from describe_all survives the structured write.
-		expect(written.data).toBeDefined();
 
-		fireEvent.click(screen.getByRole('button', { name: 'Save Changes' }));
-		expect(alterRoleMutate).toHaveBeenCalledTimes(1);
-		const [payload] = alterRoleMutate.mock.calls[0];
-		expect(payload.id).toBe('role-1');
-		expect(payload.permission.operations).toEqual(['read_only']);
-		expect(payload.permission.data).toBeDefined();
+		const permission = save();
+		expect(permission.operations).toEqual(['read_only']);
+		expect(permission.data).toEqual(readOnlyDog([]));
 	});
 
 	it('drops the allowlist when saving a super_user role, which Harper would otherwise reject', async () => {
@@ -120,26 +328,21 @@ describe('EditRoleModal operations wiring', () => {
 		// …and the conflict is stated before the author saves.
 		expect(screen.getByText(/does not accept an operations allowlist/)).toBeTruthy();
 
-		fireEvent.click(screen.getByRole('button', { name: 'Save Changes' }));
-		expect(alterRoleMutate).toHaveBeenCalledTimes(1);
-		const [payload] = alterRoleMutate.mock.calls[0];
 		// validateNoSUPerms rejects a multi-key permission with super_user: true.
-		expect(payload.permission).toEqual({ super_user: true });
+		expect(save()).toEqual({ super_user: true });
 	});
 
 	it('keeps the allowlist when saving a structure_user role, which Harper accepts', async () => {
 		renderModal({ structure_user: true, operations: ['read_only'] });
 
 		await screen.findByRole('switch', { name: 'Restrict operations' });
-		fireEvent.click(screen.getByRole('button', { name: 'Save Changes' }));
-		const [payload] = alterRoleMutate.mock.calls[0];
-		expect(payload.permission).toEqual({ structure_user: true, operations: ['read_only'] });
+		expect(save()).toEqual({ structure_user: true, operations: ['read_only'] });
 	});
 
 	it('states the instance-wide consequence for a record-shaped operations value', async () => {
 		// cacheExpandedOperationsPerms guards on truthiness only, so this reaches expandOperationsPerms
 		// and throws during the user-cache load, failing auth for every user on the instance.
-		renderModal({ operations: { tables: {} } } as unknown as LocalRole['permission']);
+		renderModal({ operations: { tables: {} } });
 
 		expect(await screen.findByText(/authentication breaks for every user/)).toBeTruthy();
 		// The old copy invited exactly the edit that keeps the instance broken.
@@ -153,54 +356,10 @@ describe('EditRoleModal operations wiring', () => {
 	it('blocks Save while a string-shaped operations value would be normalized away', async () => {
 		// preparePermissionForSave drops a non-array value, so saving an unrelated edit on this role
 		// would remove a restriction Harper is currently enforcing.
-		renderModal({ structure_user: true, operations: 'read_only' } as unknown as LocalRole['permission']);
+		renderModal({ structure_user: true, operations: 'read_only' });
 
-		expect(await screen.findByText(/not a list of operation names/)).toBeTruthy();
+		expect(await screen.findByText(/value is not a list of operation names/)).toBeTruthy();
 		expect(screen.getByRole('button', { name: 'Save Changes' }).hasAttribute('disabled')).toBe(true);
-		expect(alterRoleMutate).not.toHaveBeenCalled();
-	});
-});
-
-// A stored `attribute_permissions: null` makes every `['*']` read the role sends 500 (#1299,
-// HarperFast/harper#3143), so no save may send one.
-describe('EditRoleModal attribute_permissions', () => {
-	const readOnlyDog = (attributePermissions: unknown) => ({
-		tables: {
-			dog: { read: true, insert: false, update: false, delete: false, attribute_permissions: attributePermissions },
-		},
-	});
-
-	function grantDogReadAndSave(editor: HTMLTextAreaElement) {
-		const document = JSON.parse(editor.value) as { data: { tables: { dog: { read: boolean } } } };
-		document.data.tables.dog.read = true;
-		fireEvent.change(editor, { target: { value: JSON.stringify(document, null, 2) } });
-		fireEvent.click(screen.getByRole('button', { name: 'Save Changes' }));
-		expect(alterRoleMutate).toHaveBeenCalledTimes(1);
-		const [payload] = alterRoleMutate.mock.calls[0];
-		return payload.permission as Record<string, unknown>;
-	}
-
-	it('saves a new read-only role with an empty attribute_permissions array', async () => {
-		// The shape AddRoleModal creates before the author picks table permissions here.
-		renderModal({ super_user: false, structure_user: false });
-
-		const editor = await screen.findByRole('textbox', { name: 'Role permission JSON' }) as HTMLTextAreaElement;
-		await screen.findByDisplayValue(/"dog"/);
-		const permission = grantDogReadAndSave(editor);
-		expect(permission.data).toEqual(readOnlyDog([]));
-	});
-
-	it('repairs a role already stored with null when it is saved again', async () => {
-		renderModal({ super_user: false, data: readOnlyDog(null) } as unknown as LocalRole['permission']);
-
-		const editor = await screen.findByRole('textbox', { name: 'Role permission JSON' }) as HTMLTextAreaElement;
-		await screen.findByDisplayValue(/"dog"/);
-		// The editor already shows the repaired template; put `null` back to reach the save-side repair.
-		fireEvent.change(editor, {
-			target: { value: JSON.stringify({ super_user: false, data: readOnlyDog(null) }, null, 2) },
-		});
-		fireEvent.click(screen.getByRole('button', { name: 'Save Changes' }));
-		const [payload] = alterRoleMutate.mock.calls[0];
-		expect(payload.permission).toEqual({ super_user: false, data: readOnlyDog([]) });
+		expect(mocks.alterRoleMutate).not.toHaveBeenCalled();
 	});
 });
diff --git a/src/features/instance/config/roles/modals/EditRoleModal.tsx b/src/features/instance/config/roles/modals/EditRoleModal.tsx
index b32c20914..fbd7eabce 100644
--- a/src/features/instance/config/roles/modals/EditRoleModal.tsx
+++ b/src/features/instance/config/roles/modals/EditRoleModal.tsx
@@ -1,44 +1,19 @@
 import { ConfirmDeletionModal } from '@/components/ConfirmDeletionModal';
-import { TextLoadingSkeleton } from '@/components/TextLoadingSkeleton';
 import { Button } from '@/components/ui/button';
 import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogTitle } from '@/components/ui/dialog';
-import { Input } from '@/components/ui/input';
-import { Label } from '@/components/ui/label';
 import { useInstanceClientIdParams } from '@/config/useInstanceClient';
-import { calculateDefaultPermissions } from '@/features/instance/config/roles/defaultCalculator';
-import { OperationsAllowlistEditor } from '@/features/instance/config/roles/operations/OperationsAllowlistEditor';
-import { supportsOperationsAllowlist } from '@/features/instance/config/roles/operations/operationsCatalog';
-import { OperationsValueNotice } from '@/features/instance/config/roles/operations/OperationsValueNotice';
+import {
+	isOperationsValueUnusable,
+	RolePermissionEditor,
+	useRoleEditorSchema,
+} from '@/features/instance/config/roles/editor/RolePermissionEditor';
+import { useRolePermissionDraft } from '@/features/instance/config/roles/editor/useRolePermissionDraft';
 import { preparePermissionForSave } from '@/features/instance/config/roles/preparePermissionForSave';
 import { useInstanceAuth } from '@/hooks/useAuth';
-import { useCheckboxCallback } from '@/hooks/useCheckboxCallback';
-import { useMonacoTheme } from '@/hooks/useMonacoTheme';
-import { LocalRole, LocalRolePermission } from '@/integrations/api/api.patch';
+import { LocalRole } from '@/integrations/api/api.patch';
 import { useAlterRole } from '@/integrations/api/instance/auth/alterRole';
 import { useDeleteRoleMutation } from '@/integrations/api/instance/auth/deleteRole';
-import { getDescribeAllQueryOptions } from '@/integrations/api/instance/database/getDescribeAll';
-import { getRegistrationInfoQueryOptions } from '@/integrations/api/instance/status/getRegistrationInfo';
-import {
-	classifyOperationsValue,
-	getOperationsAllowlist,
-	orderPermissionKeys,
-	rolePreventsOperationsAllowlist,
-	structureUserDdlScope,
-	withOperations,
-} from '@/integrations/api/localRolePermission';
-import { Editor } from '@/lib/monaco/MonacoEditor';
-import { safeParse } from '@/lib/string/safeParse';
-
-/** JSON.parse without safeParse's console.error, for text that is expected to be invalid mid-edit. */
-function quietParse<T>(value: string): T | null {
-	try {
-		return JSON.parse(value) as T;
-	} catch {
-		return null;
-	}
-}
-import { useQuery } from '@tanstack/react-query';
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useState } from 'react';
 import { toast } from 'sonner';
 
 export function EditRoleModal({
@@ -58,144 +33,50 @@ export function EditRoleModal({
 	onSelectRole: (role?: string) => void;
 	onChangesSaved: () => void;
 }) {
-	const monacoTheme = useMonacoTheme();
-	const { role, permission: initialPermissions } = data;
-	const [updatedPermissions, setUpdatedPermissions] = useState<string | undefined>(
-		JSON.stringify(initialPermissions, null, 2),
-	);
-
+	const { role } = data;
 	const instanceParams = useInstanceClientIdParams();
-	const [isValidJSON, setIsValidJSON] = useState(true);
-	// Permission editing only needs the schema tree (attributes), never record counts, so skip the count
-	// scan -- and share the same count-free describe_all cache entry the Databases tab populates.
-	const { data: instanceDatabaseMap } = useQuery(
-		getDescribeAllQueryOptions({ ...instanceParams, skipRecordCount: true }),
-	);
-	const { data: registrationInfo } = useQuery(
-		getRegistrationInfoQueryOptions(instanceParams),
-	);
+	const schema = useRoleEditorSchema();
 	const auth = useInstanceAuth(instanceId ?? clusterId);
 	const isSelf = auth.user?.role?.id === data.id;
 
-	const [showAttributes, onShowAttributesChanged] = useCheckboxCallback(updatedPermissions?.includes('attribute_name'));
+	// The stored permission, as it is — never a schema-derived template, which would rewrite what it
+	// does not model. Seeded once: the roles list polls, and a refetch must not replace the draft.
+	const draft = useRolePermissionDraft(data.permission);
+	const { permission } = draft;
+	const [loadedUpdatedTime, setLoadedUpdatedTime] = useState(data.__updatedtime__);
+	const changedElsewhere = data.__updatedtime__ !== loadedUpdatedTime;
 
 	const { mutate: alterRole, isPending } = useAlterRole();
 	const { mutate: dropRole, isPending: isDeletePending } = useDeleteRoleMutation();
 	const [isConfirmDeleteModalOpen, setIsConfirmDeleteModalOpen] = useState(false);
 
-	const onValidate = useCallback(
-		(markers: unknown[]) => {
-			setIsValidJSON(markers.length === 0);
-		},
-		[setIsValidJSON],
-	);
-
-	const defaultValue = useMemo(() => {
-		return JSON.stringify(
-			instanceDatabaseMap && registrationInfo && orderPermissionKeys(calculateDefaultPermissions({
-				instanceDatabaseMap,
-				currentRolePermissions: updatedPermissions && safeParse(updatedPermissions) || initialPermissions,
-				version: registrationInfo.version,
-				showAttributes: showAttributes,
-			})),
-			null,
-			2,
-		);
-		// We exclude updatedPermissions on purpose from the deps: defaultValue must only recompute on
-		// load and when showAttributes toggles, otherwise the useEffect below overwrites the editor's
-		// value on every keystroke and Monaco jumps the cursor to the end of the input.
-		// eslint-disable-next-line react/exhaustive-deps
-	}, [initialPermissions, instanceDatabaseMap, registrationInfo, showAttributes]);
-
-	useEffect(() => {
-		setUpdatedPermissions(defaultValue);
-	}, [defaultValue]);
+	const operationsUnusable = isOperationsValueUnusable(permission, schema.version);
 
-	// The structured operations editor is a lens over the JSON text: it reads the parsed
-	// `operations` array and writes changes back into the text, which stays the single source of
-	// truth. Monaco applies programmatic value updates without firing onChange, so this can't loop.
-	const operationsSupported = supportsOperationsAllowlist(registrationInfo?.version);
-	const lastParsedRef = useRef<LocalRolePermission | null>(null);
-	const { operationsRaw, operationsJson, operationsKind, allowlistRejected, structureUserDdl } = useMemo(() => {
-		// Without the operations section there is no reader for this parse, so skip it — the
-		// permission document can be large and this recomputes per keystroke.
-		// Not safeParse: it console.errors on failure, and a half-typed document is invalid on most
-		// keystrokes — that would flood the console and RUM with expected syntax errors.
-		const parsed = operationsSupported && updatedPermissions
-			? quietParse<LocalRolePermission>(updatedPermissions)
-			: null;
-		const usable = isValidJSON && parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
-			? parsed
-			// Mid-edit the JSON is briefly unparseable; describing the role from the last good parse
-			// beats telling the author it has no restriction while they fix a comma.
-			: lastParsedRef.current;
-		if (usable === null) {
-			return {
-				operationsRaw: undefined,
-				operationsJson: undefined,
-				operationsKind: 'absent' as const,
-				allowlistRejected: false,
-				structureUserDdl: false as const,
-			};
+	const onSubmitClick = useCallback(() => {
+		if (!permission || operationsUnusable) {
+			return;
 		}
-		lastParsedRef.current = usable;
-		const allowlist = getOperationsAllowlist(usable);
-		// A present-but-not-string-array `operations` (e.g. `true`) is left to the JSON editor
-		// rather than clobbered from the structured one.
-		return {
-			operationsRaw: usable.operations,
-			operationsJson: allowlist && JSON.stringify(allowlist),
-			operationsKind: classifyOperationsValue(usable, operationsSupported),
-			allowlistRejected: rolePreventsOperationsAllowlist(usable),
-			structureUserDdl: structureUserDdlScope(usable),
-		};
-	}, [operationsSupported, isValidJSON, updatedPermissions]);
-	// Keyed on the serialized form so unrelated typing in the JSON editor keeps the array identity
-	// stable and doesn't re-render the picker subtree.
-	const operationsValue = useMemo(
-		() => (operationsJson === undefined ? undefined : JSON.parse(operationsJson) as string[]),
-		[operationsJson],
-	);
-
-	const onOperationsChanged = useCallback(
-		(next: string[] | undefined) => {
-			setUpdatedPermissions((current) => {
-				const parsed = current ? safeParse<LocalRolePermission>(current) : null;
-				if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-					return current;
-				}
-				// withOperations also floats the reserved keys (operations included) to the top of the
-				// document, where the allowlist is visible without scrolling past table permissions.
-				return JSON.stringify(withOperations(parsed, next), null, 2);
-			});
-		},
-		[],
-	);
+		alterRole(
+			{
+				id: data.id,
+				permission: preparePermissionForSave(permission),
+				...instanceParams,
+			},
+			{
+				onSuccess: () => {
+					toast.success('Role updated successfully!');
+					onSelectRole(undefined);
+					onChangesSaved();
+				},
+			},
+		);
+	}, [alterRole, data.id, instanceParams, onChangesSaved, onSelectRole, operationsUnusable, permission]);
 
-	const onRoleUpdated = useCallback(
-		(updatedPermissions: string) => {
-			// Monaco's validation markers lag typing, so isValidJSON can be stale-true at click time.
-			const parsed = safeParse<LocalRolePermission>(updatedPermissions);
-			if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-				const parsedPermissions = preparePermissionForSave(parsed);
-				alterRole(
-					{
-						id: data.id,
-						permission: parsedPermissions,
-						...instanceParams,
-					},
-					{
-						onSuccess: () => {
-							toast.success('Role updated successfully!');
-							onSelectRole(undefined);
-							onChangesSaved();
-						},
-					},
-				);
-			}
-		},
-		[alterRole, data.id, instanceParams, onChangesSaved, onSelectRole],
-	);
+	const { setPermission } = draft;
+	const onLoadLatestClick = useCallback(() => {
+		setLoadedUpdatedTime(data.__updatedtime__);
+		setPermission(data.permission);
+	}, [data.__updatedtime__, data.permission, setPermission]);
 
 	const onRoleDeleted = useCallback(() => {
 		dropRole(
@@ -213,21 +94,6 @@ export function EditRoleModal({
 		);
 	}, [data.id, dropRole, instanceParams, onChangesSaved, onSelectRole]);
 
-	const operationsUnusable = operationsKind === 'breaks-auth' || operationsKind === 'malformed';
-	// Only a record implies a database of that name, which is the half the remedy has to mention.
-	const operationsIsRecord = operationsRaw !== null && typeof operationsRaw === 'object'
-		&& !Array.isArray(operationsRaw);
-
-	const onSubmitClick = useCallback(() => {
-		if (updatedPermissions && isValidJSON) {
-			onRoleUpdated(updatedPermissions);
-		}
-	}, [updatedPermissions, onRoleUpdated, isValidJSON]);
-
-	const onRoleDeleteClick = useCallback(() => {
-		setIsConfirmDeleteModalOpen(true);
-	}, []);
-
 	return (
 		<>
 			<Dialog onOpenChange={closeModal} open={isModalOpen}>
@@ -237,73 +103,34 @@ export function EditRoleModal({
 						{isSelf
 							? 'You can view your own role, but you cannot edit it. Please assign yourself a different'
 								+ ' role to edit this role.'
-							: "Edit the role's permissions in JSON format or remove the role entirely."}
+							: 'Choose what this role can access, or remove the role entirely.'}
 					</DialogDescription>
-					{operationsSupported && registrationInfo && (
-						operationsUnusable
-							? (
-								<OperationsValueNotice
-									kind={operationsKind as 'breaks-auth' | 'malformed'}
-									databaseCollision={operationsIsRecord}
-								/>
-							)
-							: (
-								<OperationsAllowlistEditor
-									allowlistRejected={allowlistRejected}
-									structureUserDdl={structureUserDdl}
-									value={operationsValue}
-									onChange={onOperationsChanged}
-									version={registrationInfo.version}
-									disabled={isSelf || !isValidJSON}
-								/>
-							)
+					{changedElsewhere && (
+						<div className="flex flex-wrap items-center gap-2 text-xs text-warning" role="status">
+							<span>
+								This role was changed somewhere else after you opened it. Saving replaces that version with this one.
+							</span>
+							<Button type="button" size="sm" variant="defaultOutline" onClick={onLoadLatestClick}>
+								Load the latest version
+							</Button>
+						</div>
 					)}
-					<div className="flex-1 min-h-0">
-						{defaultValue
-							? (
-								<Editor
-									className="w-full h-full"
-									theme={monacoTheme}
-									defaultLanguage="json"
-									value={updatedPermissions}
-									options={{ readOnly: isSelf, automaticLayout: true }}
-									onValidate={onValidate}
-									onChange={setUpdatedPermissions}
-									defaultValue={defaultValue}
-								/>
-							)
-							: <TextLoadingSkeleton />}
-					</div>
+					<RolePermissionEditor draft={draft} schema={schema} readOnly={isSelf} />
 					<DialogFooter>
 						{!isSelf && (
 							<div className="flex justify-between w-full">
 								<Button
 									type="button"
 									variant="destructiveOutline"
-									onClick={onRoleDeleteClick}
+									onClick={() => setIsConfirmDeleteModalOpen(true)}
 									disabled={isPending}
 								>
 									Delete Role
 								</Button>
-
-								<div className="grow" />
-
-								<Label className="flex">
-									<Input
-										type="checkbox"
-										className="w-6"
-										checked={showAttributes}
-										onChange={onShowAttributesChanged}
-									/>
-									<span className="pl-4 pr-8 flex-1 py-2.5">Pick Attributes</span>
-								</Label>
-
 								<Button
 									variant="submit"
 									onClick={onSubmitClick}
-									// Saving past an unusable `operations` value would normalize it away and widen the
-									// role, so the value has to be repaired in the JSON first.
-									disabled={isPending || !isValidJSON || operationsUnusable}
+									disabled={isPending || !permission || operationsUnusable}
 								>
 									Save Changes
 								</Button>
diff --git a/src/features/instance/config/roles/preparePermissionForSave.test.ts b/src/features/instance/config/roles/preparePermissionForSave.test.ts
index 4a9ba1144..f82992153 100644
--- a/src/features/instance/config/roles/preparePermissionForSave.test.ts
+++ b/src/features/instance/config/roles/preparePermissionForSave.test.ts
@@ -95,6 +95,15 @@ describe('preparePermissionForSave', () => {
 		expect(preparePermissionForSave(clusterUser)).toEqual({ cluster_user: true });
 	});
 
+	it('drops structure_user beside super_user or cluster_user, whatever its value', () => {
+		// validateNoSUPerms counts keys, so `{ super_user: true, structure_user: true }` is rejected as
+		// surely as a table permission — which a role-type switch in the editor can produce.
+		expect(preparePermissionForSave({ super_user: true, structure_user: true })).toEqual({ super_user: true });
+		expect(preparePermissionForSave({ cluster_user: true, structure_user: ['data'], ...tablePerms })).toEqual({
+			cluster_user: true,
+		});
+	});
+
 	it('keeps the allowlist for a structure_user role, which Harper does accept and enforce', () => {
 		const permission: LocalRolePermission = {
 			structure_user: true,
diff --git a/src/features/instance/config/roles/preparePermissionForSave.ts b/src/features/instance/config/roles/preparePermissionForSave.ts
index 19975bed4..78942035b 100644
--- a/src/features/instance/config/roles/preparePermissionForSave.ts
+++ b/src/features/instance/config/roles/preparePermissionForSave.ts
@@ -6,11 +6,11 @@ import { RESERVED_PERMISSION_KEYS, rolePreventsOperationsAllowlist } from '@/int
  * Roles that are unconditionally super/structure/cluster users don't need per-table permissions,
  * so those are dropped for them. False top-level flags are dropped as noise.
  *
- * `operations` survives only where Harper accepts it: `validateNoSUPerms` rejects any multi-key
- * permission setting `super_user: true` or `cluster_user: true`, so keeping the allowlist there
- * would fail the save outright — it is dropped alongside the table permissions instead. A
- * `structure_user` role may carry one (the gate still runs for everything but DDL), and it
- * survives only as an actual array: any other shape under that key is not an allowlist.
+ * `validateNoSUPerms` rejects any multi-key permission setting `super_user: true` or
+ * `cluster_user: true`, so such a role is sent with nothing beside its flag: the allowlist and a
+ * `structure_user` value (even `true`) would each fail the save outright. A `structure_user` role
+ * may carry an allowlist (the gate still runs for everything but DDL), and it survives only as an
+ * actual array: any other shape under that key is not an allowlist.
  *
  * `structure_user` may also be an array of database names, which grants DDL on *those* databases
  * only — such a role still relies on its explicit table permissions elsewhere, so it keeps them.
@@ -26,12 +26,13 @@ export function preparePermissionForSave(parsedPermissions: LocalRolePermission)
 	) {
 		return withAttributePermissionArrays(parsedPermissions);
 	}
-	const allowlistRejected = rolePreventsOperationsAllowlist(parsedPermissions);
+	const flagStandsAlone = rolePreventsOperationsAllowlist(parsedPermissions);
 	const prepared = { ...parsedPermissions };
 	for (const key in prepared) {
 		if (
 			!RESERVED_PERMISSION_KEYS.has(key)
-			|| (key === 'operations' && (allowlistRejected || !Array.isArray(prepared.operations)))
+			|| (key === 'operations' && (flagStandsAlone || !Array.isArray(prepared.operations)))
+			|| (key === 'structure_user' && flagStandsAlone)
 		) {
 			// If you're a super, structure or cluster user, you don't need more specific permissions.
 			delete prepared[key];
diff --git a/src/integrations/api/instance/auth/addRole.ts b/src/integrations/api/instance/auth/addRole.ts
index 0251b7dc6..53701ca08 100644
--- a/src/integrations/api/instance/auth/addRole.ts
+++ b/src/integrations/api/instance/auth/addRole.ts
@@ -1,28 +1,24 @@
 import { InstanceClientConfig } from '@/config/instanceClientConfig';
-import { LocalRole } from '@/integrations/api/api.patch';
+import { LocalRole, LocalRolePermission } from '@/integrations/api/api.patch';
 import { useMutation } from '@tanstack/react-query';
 
 export interface AddRoleFormData {
 	role: string;
-	super_user?: boolean;
-	structure_user?: boolean;
 }
 
-export async function onAddRoleSubmit(formData: AddRoleFormData & InstanceClientConfig): Promise<LocalRole> {
-	const { role, super_user, structure_user, instanceClient } = formData;
+interface AddRoleRequest extends AddRoleFormData, InstanceClientConfig {
+	permission: LocalRolePermission;
+}
+
+export async function onAddRoleSubmit({ role, permission, instanceClient }: AddRoleRequest): Promise<LocalRole> {
 	const { data } = await instanceClient.post(
 		'/',
 		{
 			operation: 'add_role',
 			role,
-			permission: {
-				super_user,
-				structure_user,
-			},
+			permission,
 		},
 	);
-	// add_role echoes back the created role, including its unique `id`, which we use to navigate
-	// to the new role for editing (role names are not unique, so the name can't identify it).
 	return data as LocalRole;
 }
 
diff --git a/src/integrations/api/instance/auth/addRoleFormSchema.ts b/src/integrations/api/instance/auth/addRoleFormSchema.ts
index 494c51432..48b3553b0 100644
--- a/src/integrations/api/instance/auth/addRoleFormSchema.ts
+++ b/src/integrations/api/instance/auth/addRoleFormSchema.ts
@@ -10,6 +10,4 @@ export const AddRoleFormSchema = z.object({
 		.max(30, {
 			error: 'Role cannot be longer than 30 characters.',
 		}),
-	super_user: z.boolean(),
-	structure_user: z.boolean(),
 });

From 2dbf7fab02bf0187966a91278b4fa52b87e16b31 Mon Sep 17 00:00:00 2001
From: Dawson Toth <dawson@harperdb.io>
Date: Sun, 11 Oct 2026 04:33:39 -0400
Subject: [PATCH 2/7] fix(roles): keep each role's draft its own, and block
 saving over a newer version

From the first cross-model review round of the visual role editor:

- The edit modal is keyed on the role id. Its draft is seeded once, so
  moving straight from one role to another reused the first draft and
  Save sent it to the second role.
- A newer stored version (polled __updatedtime__) now blocks Save until
  the author loads it or chooses to keep theirs; alter_role replaces the
  whole permission with no revision check.
- The derived primary key counts every listed attribute, including ones
  describe_all does not show, as Harper's permission translator does.
- Only one database section opens by default, so a broad role on a large
  instance does not mount every table grid up front.
- The cluster user option says what it means per version: on Harper 4 a
  user with that role has its password stored reversibly for clustering;
  Harper 5 does not use the flag.
- A table entry without attribute_permissions gets a blocker that says
  how to fix it, and schema tables without an attributes array no longer
  throw.

Refs #1634

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/features/instance/config/roles/DESIGN.md  |  9 +-
 .../roles/editor/RoleVisualEditor.test.tsx    | 13 ++-
 .../config/roles/editor/RoleVisualEditor.tsx  | 28 +++---
 .../roles/editor/rolePermissionModel.test.ts  | 16 ++++
 .../roles/editor/rolePermissionModel.ts       | 21 ++++-
 .../instance/config/roles/index.test.tsx      | 91 +++++++++++++++++++
 src/features/instance/config/roles/index.tsx  |  2 +
 .../roles/modals/EditRoleModal.test.tsx       | 20 +++-
 .../config/roles/modals/EditRoleModal.tsx     | 35 +++++--
 .../roles/preparePermissionForSave.test.ts    |  2 +
 10 files changed, 207 insertions(+), 30 deletions(-)
 create mode 100644 src/features/instance/config/roles/index.test.tsx

diff --git a/src/features/instance/config/roles/DESIGN.md b/src/features/instance/config/roles/DESIGN.md
index 1ed6863af..43d528f2c 100644
--- a/src/features/instance/config/roles/DESIGN.md
+++ b/src/features/instance/config/roles/DESIGN.md
@@ -38,9 +38,16 @@ beside `super_user` / `cluster_user`, which is everything, `structure_user` incl
 type in the GUI keeps everything else in the draft until then, so switching back within a session
 loses nothing.
 
+The draft is seeded once per modal instance. The roles list polls, so a refetch must never replace
+an open draft. Selecting another role must therefore mount a new modal, which is why `index.tsx`
+keys the modal on the role id. `alter_role` replaces the whole permission with no revision check,
+so the modal compares the role's `__updatedtime__` with the one it loaded. A newer one blocks Save
+until the author loads that version or chooses to keep their own.
+
 A visual edit keeps the object it produced instead of re-parsing its own text. That keeps object
 identity for every untouched database and table, so the memoized `DatabaseSection` / `TableRows`
-re-render only what changed, which matters on a schema with hundreds of tables.
+re-render only what changed, which matters on a schema with hundreds of tables. For the same reason
+only one database section opens by default, because an open section mounts its whole table grid.
 
 The Harper semantics the editor shows are written down where they are encoded. The effective
 attribute access, including the derived primary key and timestamps being read-only, is in
diff --git a/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx b/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx
index 5fc050c7f..c650c1869 100644
--- a/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx
+++ b/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx
@@ -140,9 +140,18 @@ describe('RoleVisualEditor', () => {
 
 	it('offers the cluster user type on Harper 4, and to a role that already has it', () => {
 		renderEditor({}, '4.7.40');
-		expect(screen.getByRole('radio', { name: /Cluster user/ })).toBeTruthy();
+		// Harper 4 stores such a user's password reversibly encrypted (harperdb security/user.ts).
+		expect(screen.getByRole('radio', { name: /Cluster user.*recoverable form/ })).toBeTruthy();
 		cleanup();
 		renderEditor({ cluster_user: true });
-		expect(screen.getByRole('radio', { name: /Cluster user/ }).getAttribute('aria-checked')).toBe('true');
+		const radio = screen.getByRole('radio', { name: /Cluster user.*Harper 5 doesn't use this role type/ });
+		expect(radio.getAttribute('aria-checked')).toBe('true');
+	});
+
+	it('opens only one database on a role that grants several, so a large schema stays cheap to open', () => {
+		renderEditor({ data: { tables: { dog: table(true) } }, dev: { tables: { thing: table(true) } } });
+
+		expect(screen.getByRole('checkbox', { name: 'Read on data.dog' })).toBeTruthy();
+		expect(screen.queryByRole('checkbox', { name: 'Read on dev.thing' })).toBeNull();
 	});
 });
diff --git a/src/features/instance/config/roles/editor/RoleVisualEditor.tsx b/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
index b9cafb16c..6d6878cc4 100644
--- a/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
+++ b/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
@@ -11,6 +11,7 @@ import {
 	getEditableDatabaseNames,
 	getPreservedEntries,
 	getRoleType,
+	getTableAttributeNames,
 	getTableEntry,
 	getTableEntryInRecord,
 	getTablePrimaryKey,
@@ -191,9 +192,11 @@ function RoleTypeSection({
 	onChange: (next: LocalRolePermission) => void;
 }) {
 	const id = useId();
-	// Only Harper 4 gives this flag a meaning (it marks the role of the user that connects cluster
-	// nodes); nothing in Harper 5 reads it, so it is offered there only to a role that already has it.
-	const offerClusterUser = roleType === 'cluster_user' || !wasAReleasedBeforeB('5.0.0', version);
+	// Only Harper 4 gives this flag a meaning: it marks the user clustering connects as, and that user's
+	// password is then stored reversibly encrypted (harperdb security/user.ts). Nothing in Harper 5 reads
+	// it, so it is offered there only to a role that already has it.
+	const harper4 = !wasAReleasedBeforeB('5.0.0', version);
+	const offerClusterUser = roleType === 'cluster_user' || harper4;
 	const dropsOthers = roleType !== 'standard' && carriesOtherPermissions(permission, roleType);
 	return (
 		<section className="flex flex-col gap-2" aria-labelledby={`${id}-heading`}>
@@ -212,7 +215,9 @@ function RoleTypeSection({
 				</RadioOption>
 				{offerClusterUser && (
 					<RadioOption id={`${id}-cluster`} value="cluster_user" label="Cluster user">
-						Harper 4 uses this role type for the user that connects cluster nodes.
+						{harper4
+							? 'For the user that connects cluster nodes. Harper keeps the password of a user with this role in a recoverable form so clustering can use it.'
+							: "Harper 5 doesn't use this role type. Harper 4 used it for the user that connects cluster nodes."}
 					</RadioOption>
 				)}
 			</RadioGroup>
@@ -337,16 +342,16 @@ function TablePermissionsSection({
 	readOnly?: boolean;
 	onChange: (next: LocalRolePermission) => void;
 }) {
-	// Databases the role already grants something on open expanded, so the role reads at a glance;
-	// a role with no grants yet opens the first one as a starting point.
+	// One database opens, never all of them: an open database mounts its whole table grid, so a broad
+	// role on a large instance would otherwise render every table before the modal appears.
 	const [openDatabases, setOpenDatabases] = useState<string[]>(() => {
-		const granted = databaseNames.filter((databaseName) =>
+		const firstGranted = databaseNames.find((databaseName) =>
 			Object.keys(instanceDatabaseMap[databaseName]).some((tableName) => {
 				const entry = getTableEntry(permission, databaseName, tableName);
 				return entry && TABLE_ACTIONS.some((action) => entry[action] === true);
 			})
 		);
-		return granted.length ? granted : databaseNames.slice(0, 1);
+		return [firstGranted ?? databaseNames[0]].filter((name) => name !== undefined);
 	});
 	// Survives turning attribute scoping off and on again within the session, like the operations
 	// switch does for its allowlist.
@@ -506,10 +511,7 @@ const TableRows = memo(function TableRows({
 	update: (patch: PermissionPatch) => void;
 	scopingRestore: Map<string, LocalRoleAttributePermissionTable[]>;
 }) {
-	const attributeNames = useMemo(
-		() => schemaTable.attributes.map((attribute) => attribute.attribute),
-		[schemaTable],
-	);
+	const attributeNames = useMemo(() => getTableAttributeNames(schemaTable), [schemaTable]);
 	const primaryKey = getTablePrimaryKey(schemaTable);
 	const scoped = isTableScopedToAttributes(entry);
 	const [expanded, setExpanded] = useState(false);
@@ -625,7 +627,7 @@ function AttributePanel({
 			</div>
 			<p className="text-xs text-muted-foreground">
 				{scoped
-					? "Only the access checked here applies. An attribute with nothing checked has no access, including attributes added to the table later. Computed attributes aren't listed here; grant them in the JSON."
+					? 'Only the access checked here applies. An attribute with nothing checked has no access, including attributes added to the table later. Computed and relationship attributes may be missing from this list; grant those in the JSON.'
 					: "The table's read, insert and update apply to every attribute."}
 			</p>
 			{scoped && (
diff --git a/src/features/instance/config/roles/editor/rolePermissionModel.test.ts b/src/features/instance/config/roles/editor/rolePermissionModel.test.ts
index 5ffd42690..0e9c2c81d 100644
--- a/src/features/instance/config/roles/editor/rolePermissionModel.test.ts
+++ b/src/features/instance/config/roles/editor/rolePermissionModel.test.ts
@@ -124,6 +124,13 @@ describe('getVisualEditorBlockers', () => {
 		expect(getVisualEditorBlockers(duplicated, schema, VERSION)).toEqual([
 			'"data.cat.attribute_permissions" lists "name" more than once.',
 		]);
+		// Harper's role validation requires the key (ATTR_PERMS_ARRAY_MISSING), so say how to add it.
+		const missing = asPermission({
+			data: { tables: { cat: { read: true, insert: false, update: false, delete: false } } },
+		});
+		expect(getVisualEditorBlockers(missing, schema, VERSION)).toEqual([
+			'"data.cat" needs an "attribute_permissions" list ([] applies the table\'s access to every attribute).',
+		]);
 		const legacy = asPermission({ data: { tables: { cat: { ...entry(true), attribute_restrictions: [] } } } });
 		expect(getVisualEditorBlockers(legacy, schema, VERSION)).toHaveLength(1);
 		expect(getVisualEditorBlockers({}, schema, '2.1.2')).toHaveLength(1);
@@ -294,6 +301,15 @@ describe('attribute scoping', () => {
 		]);
 	});
 
+	it('derives the primary key from listed attributes the schema does not show, as Harper does', () => {
+		// describe_all omits `@computed` attributes unless asked, but Harper still counts their entries.
+		const dog = entry(true, false, false, false, [
+			{ attribute_name: 'computed_score', read: true, insert: false, update: false },
+		]);
+		const id = getAttributeViews(dog as never, dogAttributes, 'id').find((view) => view.name === 'id');
+		expect(id).toMatchObject({ read: true, derived: true });
+	});
+
 	it('adds an unlisted attribute with its effective access before flipping one action', () => {
 		const permission = asPermission({
 			data: {
diff --git a/src/features/instance/config/roles/editor/rolePermissionModel.ts b/src/features/instance/config/roles/editor/rolePermissionModel.ts
index c7dfbefa4..3cd6da4ed 100644
--- a/src/features/instance/config/roles/editor/rolePermissionModel.ts
+++ b/src/features/instance/config/roles/editor/rolePermissionModel.ts
@@ -99,7 +99,11 @@ export function getEditableDatabaseNames(instanceDatabaseMap: InstanceDatabaseMa
 
 export function getTablePrimaryKey(table: InstanceTable): string | undefined {
 	return table.primary_key ?? table.hash_attribute
-		?? table.attributes.find((attribute) => attribute.is_primary_key)?.attribute;
+		?? table.attributes?.find((attribute) => attribute.is_primary_key)?.attribute;
+}
+
+export function getTableAttributeNames(table: InstanceTable): string[] {
+	return (table.attributes ?? []).map((attribute) => attribute.attribute);
 }
 
 /** Keys of the document that name databases rather than role flags or the allowlist. */
@@ -191,6 +195,12 @@ function getTableEntryBlockers(entry: unknown, label: string): string[] {
 	if (attributePermissions === null) {
 		return blockers;
 	}
+	if (attributePermissions === undefined) {
+		blockers.push(
+			`"${label}" needs an "attribute_permissions" list ([] applies the table's access to every attribute).`,
+		);
+		return blockers;
+	}
 	if (!Array.isArray(attributePermissions)) {
 		blockers.push(`"${label}.attribute_permissions" must be a list.`);
 		return blockers;
@@ -295,7 +305,7 @@ export function getPreservedEntries(
 			if (!Array.isArray(attributePermissions)) {
 				continue;
 			}
-			const schemaAttributes = new Set(schemaTable.attributes.map((attribute) => attribute.attribute));
+			const schemaAttributes = new Set(getTableAttributeNames(schemaTable));
 			for (const attributeEntry of attributePermissions) {
 				if (!isPlainRecord(attributeEntry)) {
 					continue;
@@ -528,10 +538,11 @@ export function getAttributeViews(
 			update: !timestamp && attribute?.update === true,
 		};
 	};
+	// Every listed attribute counts, including ones describe_all does not show (`@computed`, or
+	// relationships on 5.x): Harper only stores an entry for an attribute its schema has.
 	const derivedPrimaryKey = { read: false, insert: false, update: false };
-	for (const name of attributeNames) {
-		const attribute = listed.get(name);
-		if (name !== primaryKey && attribute) {
+	for (const [name, attribute] of listed) {
+		if (name !== primaryKey) {
 			const access = effective(name, attribute);
 			for (const action of ATTRIBUTE_ACTIONS) {
 				derivedPrimaryKey[action] ||= access[action];
diff --git a/src/features/instance/config/roles/index.test.tsx b/src/features/instance/config/roles/index.test.tsx
new file mode 100644
index 000000000..54f798048
--- /dev/null
+++ b/src/features/instance/config/roles/index.test.tsx
@@ -0,0 +1,91 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { ConfigRolesIndex } from '@/features/instance/config/roles/index';
+import { LocalRole } from '@/integrations/api/api.patch';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { ReactNode } from 'react';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({ alterRoleMutate: vi.fn(), params: { roleId: 'role-a' as string | undefined } }));
+
+vi.mock('@tanstack/react-router', () => ({
+	useNavigate: () => vi.fn(),
+	useParams: () => mocks.params,
+}));
+vi.mock('@/components/SimpleBrowseDataTable', () => ({
+	SimpleBrowseDataTable: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+}));
+vi.mock('@/features/instance/config/roles/operations/AllowlistSupportedContext', () => ({
+	AllowlistSupportedProvider: ({ children }: { children: ReactNode }) => children,
+}));
+vi.mock('@/lib/monaco/MonacoEditor', () => ({ Editor: () => null }));
+vi.mock('@/hooks/useMonacoTheme', () => ({ useMonacoTheme: () => 'vs-dark' }));
+vi.mock('@/config/useInstanceClient', () => ({ useInstanceClientIdParams: () => ({}) }));
+vi.mock('@/hooks/useAuth', () => ({ useInstanceAuth: () => ({ user: { role: { id: 'someone-else' } } }) }));
+vi.mock('@/integrations/api/instance/auth/alterRole', () => ({
+	useAlterRole: () => ({ mutate: mocks.alterRoleMutate, isPending: false }),
+}));
+vi.mock('@/integrations/api/instance/auth/deleteRole', () => ({
+	useDeleteRoleMutation: () => ({ mutate: vi.fn(), isPending: false }),
+}));
+vi.mock('@/integrations/api/instance/database/getDescribeAll', () => ({
+	getDescribeAllQueryOptions: () => ({
+		queryKey: ['test', 'describe_all'],
+		queryFn: () => ({ data: { dog: { primary_key: 'id', attributes: [{ attribute: 'id' }] } } }),
+	}),
+}));
+vi.mock('@/integrations/api/instance/status/getRegistrationInfo', () => ({
+	getRegistrationInfoQueryOptions: () => ({
+		queryKey: ['test', 'registration_info'],
+		queryFn: () => ({ version: '5.3.1' }),
+	}),
+}));
+
+const dog = (read: boolean) => ({
+	tables: { dog: { read, insert: false, update: false, delete: false, attribute_permissions: [] } },
+});
+const roles: LocalRole[] = [
+	{ id: 'role-a', role: 'role_a', permission: { data: dog(true) }, __createdtime__: 0, __updatedtime__: 0 },
+	{ id: 'role-b', role: 'role_b', permission: { data: dog(false) }, __createdtime__: 0, __updatedtime__: 0 },
+];
+vi.mock('@/integrations/api/instance/auth/getListRoles', () => ({
+	getListRolesQueryOptions: () => ({ queryKey: ['test', 'list_roles'], queryFn: () => roles }),
+}));
+
+beforeAll(() => {
+	Element.prototype.hasPointerCapture ??= () => false;
+	Element.prototype.setPointerCapture ??= () => undefined;
+	Element.prototype.releasePointerCapture ??= () => undefined;
+	Element.prototype.scrollIntoView ??= () => undefined;
+	if (typeof window.PointerEvent === 'undefined') {
+		window.PointerEvent = class extends MouseEvent {} as typeof PointerEvent;
+	}
+});
+
+afterEach(cleanup);
+
+describe('ConfigRolesIndex', () => {
+	it('gives another role its own draft when the selected role changes while the editor is open', async () => {
+		const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+		const page = () => (
+			<QueryClientProvider client={queryClient}>
+				<ConfigRolesIndex />
+			</QueryClientProvider>
+		);
+		const { rerender } = render(page());
+		fireEvent.click(await screen.findByRole('checkbox', { name: 'Insert on data.dog' }));
+
+		mocks.params = { roleId: 'role-b' };
+		rerender(page());
+		expect(await screen.findByText('Edit Role "role_b"')).toBeTruthy();
+		expect((screen.getByRole('checkbox', { name: 'Read on data.dog' }) as HTMLInputElement).checked).toBe(false);
+		expect((screen.getByRole('checkbox', { name: 'Insert on data.dog' }) as HTMLInputElement).checked).toBe(false);
+
+		fireEvent.click(screen.getByRole('button', { name: 'Save Changes' }));
+		const [payload] = mocks.alterRoleMutate.mock.calls[0];
+		expect(payload.id).toBe('role-b');
+		expect(payload.permission).toEqual({ data: dog(false) });
+	});
+});
diff --git a/src/features/instance/config/roles/index.tsx b/src/features/instance/config/roles/index.tsx
index f45eedf2d..e31068fe7 100644
--- a/src/features/instance/config/roles/index.tsx
+++ b/src/features/instance/config/roles/index.tsx
@@ -93,6 +93,8 @@ export function ConfigRolesIndex() {
 			{isAddModalOpen && <AddRoleModal onChangesSaved={onRoleAdded} closeModal={closeAddModal} />}
 			{isEditModalOpen && (
 				<EditRoleModal
+					// Its draft is seeded once, so another role must get a fresh instance rather than reuse it.
+					key={selectedRole.id}
 					instanceId={instanceId}
 					clusterId={clusterId}
 					isModalOpen={isEditModalOpen}
diff --git a/src/features/instance/config/roles/modals/EditRoleModal.test.tsx b/src/features/instance/config/roles/modals/EditRoleModal.test.tsx
index 53453b9df..b43484eec 100644
--- a/src/features/instance/config/roles/modals/EditRoleModal.test.tsx
+++ b/src/features/instance/config/roles/modals/EditRoleModal.test.tsx
@@ -290,14 +290,32 @@ describe('EditRoleModal visual editor', () => {
 		expect(screen.queryByText(/changed somewhere else/)).toBeNull();
 		expect((screen.getByRole('checkbox', { name: 'Insert on data.dog' }) as HTMLInputElement).checked).toBe(true);
 
-		// …while a newer stored version is announced rather than silently overwritten.
+		// …while a newer stored version blocks Save: alter_role would replace it wholesale.
 		rerenderWith(roleData({ super_user: true }, 5));
 		expect(screen.getByText(/changed somewhere else/)).toBeTruthy();
+		const saveButton = screen.getByRole('button', { name: 'Save Changes' });
+		expect(saveButton.hasAttribute('disabled')).toBe(true);
+		fireEvent.click(saveButton);
+		expect(mocks.alterRoleMutate).not.toHaveBeenCalled();
+
 		fireEvent.click(screen.getByRole('button', { name: 'Load the latest version' }));
 		expect(screen.queryByText(/changed somewhere else/)).toBeNull();
 		expect((screen.getByRole('radio', { name: /Super user/ }) as HTMLButtonElement).getAttribute('aria-checked')).toBe(
 			'true',
 		);
+		expect(save()).toEqual({ super_user: true });
+	});
+
+	it('saves over a newer stored version only once the author chooses to keep theirs', async () => {
+		const { rerenderWith } = renderModal({ data: readOnlyDog([]) });
+		fireEvent.click(await screen.findByRole('checkbox', { name: 'Insert on data.dog' }));
+
+		rerenderWith(roleData({ super_user: true }, 5));
+		fireEvent.click(screen.getByRole('button', { name: 'Keep my changes' }));
+		expect(screen.queryByText(/changed somewhere else/)).toBeNull();
+		expect(save()).toEqual({
+			data: { tables: { dog: { ...readOnlyDog([]).tables.dog, insert: true } } },
+		});
 	});
 });
 
diff --git a/src/features/instance/config/roles/modals/EditRoleModal.tsx b/src/features/instance/config/roles/modals/EditRoleModal.tsx
index fbd7eabce..e2e725aff 100644
--- a/src/features/instance/config/roles/modals/EditRoleModal.tsx
+++ b/src/features/instance/config/roles/modals/EditRoleModal.tsx
@@ -39,8 +39,8 @@ export function EditRoleModal({
 	const auth = useInstanceAuth(instanceId ?? clusterId);
 	const isSelf = auth.user?.role?.id === data.id;
 
-	// The stored permission, as it is — never a schema-derived template, which would rewrite what it
-	// does not model. Seeded once: the roles list polls, and a refetch must not replace the draft.
+	// Seeded once from the stored permission (see the roles DESIGN.md): a polled refetch must not
+	// replace the draft, and a newer stored version blocks Save, since alter_role has no revision check.
 	const draft = useRolePermissionDraft(data.permission);
 	const { permission } = draft;
 	const [loadedUpdatedTime, setLoadedUpdatedTime] = useState(data.__updatedtime__);
@@ -53,7 +53,7 @@ export function EditRoleModal({
 	const operationsUnusable = isOperationsValueUnusable(permission, schema.version);
 
 	const onSubmitClick = useCallback(() => {
-		if (!permission || operationsUnusable) {
+		if (!permission || operationsUnusable || changedElsewhere) {
 			return;
 		}
 		alterRole(
@@ -70,13 +70,25 @@ export function EditRoleModal({
 				},
 			},
 		);
-	}, [alterRole, data.id, instanceParams, onChangesSaved, onSelectRole, operationsUnusable, permission]);
+	}, [
+		alterRole,
+		changedElsewhere,
+		data.id,
+		instanceParams,
+		onChangesSaved,
+		onSelectRole,
+		operationsUnusable,
+		permission,
+	]);
 
 	const { setPermission } = draft;
+	const [loadCount, setLoadCount] = useState(0);
 	const onLoadLatestClick = useCallback(() => {
-		setLoadedUpdatedTime(data.__updatedtime__);
 		setPermission(data.permission);
+		setLoadCount((count) => count + 1);
+		setLoadedUpdatedTime(data.__updatedtime__);
 	}, [data.__updatedtime__, data.permission, setPermission]);
+	const onKeepMineClick = useCallback(() => setLoadedUpdatedTime(data.__updatedtime__), [data.__updatedtime__]);
 
 	const onRoleDeleted = useCallback(() => {
 		dropRole(
@@ -108,14 +120,21 @@ export function EditRoleModal({
 					{changedElsewhere && (
 						<div className="flex flex-wrap items-center gap-2 text-xs text-warning" role="status">
 							<span>
-								This role was changed somewhere else after you opened it. Saving replaces that version with this one.
+								This role was changed somewhere else after you opened it. Load that version, or keep yours to replace it
+								when you save.
 							</span>
 							<Button type="button" size="sm" variant="defaultOutline" onClick={onLoadLatestClick}>
 								Load the latest version
 							</Button>
+							{!isSelf && (
+								<Button type="button" size="sm" variant="defaultOutline" onClick={onKeepMineClick}>
+									Keep my changes
+								</Button>
+							)}
 						</div>
 					)}
-					<RolePermissionEditor draft={draft} schema={schema} readOnly={isSelf} />
+					{/* Remounted on a load, so the editor's own state (open sections, restorable lists) starts over too. */}
+					<RolePermissionEditor key={loadCount} draft={draft} schema={schema} readOnly={isSelf} />
 					<DialogFooter>
 						{!isSelf && (
 							<div className="flex justify-between w-full">
@@ -130,7 +149,7 @@ export function EditRoleModal({
 								<Button
 									variant="submit"
 									onClick={onSubmitClick}
-									disabled={isPending || !permission || operationsUnusable}
+									disabled={isPending || !permission || operationsUnusable || changedElsewhere}
 								>
 									Save Changes
 								</Button>
diff --git a/src/features/instance/config/roles/preparePermissionForSave.test.ts b/src/features/instance/config/roles/preparePermissionForSave.test.ts
index f82992153..0f424b6ce 100644
--- a/src/features/instance/config/roles/preparePermissionForSave.test.ts
+++ b/src/features/instance/config/roles/preparePermissionForSave.test.ts
@@ -102,6 +102,8 @@ describe('preparePermissionForSave', () => {
 		expect(preparePermissionForSave({ cluster_user: true, structure_user: ['data'], ...tablePerms })).toEqual({
 			cluster_user: true,
 		});
+		// The shape the editor's role-type switch leaves behind: the other flag written as false.
+		expect(preparePermissionForSave({ super_user: false, cluster_user: true })).toEqual({ cluster_user: true });
 	});
 
 	it('keeps the allowlist for a structure_user role, which Harper does accept and enforce', () => {

From 1f0e58d736a43179db1c1ed4fdda4132a719da3b Mon Sep 17 00:00:00 2001
From: Dawson Toth <dawson@harperdb.io>
Date: Sun, 11 Oct 2026 04:42:20 -0400
Subject: [PATCH 3/7] fix(roles): don't save a malformed operations value when
 the instance version is unknown

If registration_info fails, the allowlist floor is unknown, and Save
stayed enabled for an operations value that isn't a list of names. For a
structure_user: true role, preparePermissionForSave drops that value and
widens the role. Without a version, the value now counts as unusable,
which blocks Save until it is fixed in the JSON. A real list still saves.

Also trims the editor modules' narrative doc comments down to the
invariants they guard.

Refs #1634

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../roles/editor/RolePermissionEditor.tsx     | 19 +++++++--------
 .../config/roles/editor/RoleVisualEditor.tsx  |  6 ++---
 .../roles/editor/rolePermissionModel.ts       | 10 +++-----
 .../roles/modals/EditRoleModal.test.tsx       | 24 ++++++++++++++++++-
 4 files changed, 37 insertions(+), 22 deletions(-)

diff --git a/src/features/instance/config/roles/editor/RolePermissionEditor.tsx b/src/features/instance/config/roles/editor/RolePermissionEditor.tsx
index 513802c22..1c0d63487 100644
--- a/src/features/instance/config/roles/editor/RolePermissionEditor.tsx
+++ b/src/features/instance/config/roles/editor/RolePermissionEditor.tsx
@@ -10,7 +10,7 @@ import { useMonacoTheme } from '@/hooks/useMonacoTheme';
 import { InstanceDatabaseMap, LocalRolePermission } from '@/integrations/api/api.patch';
 import { getDescribeAllQueryOptions } from '@/integrations/api/instance/database/getDescribeAll';
 import { getRegistrationInfoQueryOptions } from '@/integrations/api/instance/status/getRegistrationInfo';
-import { classifyOperationsValue } from '@/integrations/api/localRolePermission';
+import { classifyOperationsValue, getOperationsAllowlist } from '@/integrations/api/localRolePermission';
 import { Editor } from '@/lib/monaco/MonacoEditor';
 import { useQuery } from '@tanstack/react-query';
 import { CodeIcon, RefreshCwIcon, Table2Icon } from 'lucide-react';
@@ -24,7 +24,6 @@ export interface RoleEditorSchema {
 	retry: () => void;
 }
 
-/** The instance schema and version both role modals render against. */
 export function useRoleEditorSchema(): RoleEditorSchema {
 	const instanceParams = useInstanceClientIdParams();
 	// Permission editing only needs the schema tree, never record counts, so this shares the
@@ -46,13 +45,16 @@ export function useRoleEditorSchema(): RoleEditorSchema {
 
 /**
  * Saving past an unusable `operations` value would normalize it away and widen the role, so it has
- * to be repaired in the JSON first. Without a version the allowlist floor is unknown, and Harper's
- * own role validation is left to reject a malformed value.
+ * to be repaired in the JSON first. Without a version the allowlist floor is unknown, so anything
+ * but a list of names counts as unusable rather than risk dropping one.
  */
 export function isOperationsValueUnusable(permission: LocalRolePermission | null, version: string | undefined) {
-	if (!permission || !version) {
+	if (!permission) {
 		return false;
 	}
+	if (!version) {
+		return permission.operations !== undefined && getOperationsAllowlist(permission) === undefined;
+	}
 	const kind = classifyOperationsValue(permission, supportsOperationsAllowlist(version));
 	return kind === 'breaks-auth' || kind === 'malformed';
 }
@@ -60,11 +62,8 @@ export function isOperationsValueUnusable(permission: LocalRolePermission | null
 const MAX_LISTED_BLOCKERS = 5;
 
 /**
- * Visual-first role permission editor with a JSON escape hatch (HarperFast/studio#1634), mirroring
- * the schema editor's toggle. The draft's text is the single source of truth: the visual editor
- * patches the parsed document and writes the result back, and the JSON view edits the text
- * directly, so switching views never loses an edit. The visual view is offered only while the text
- * holds a document it can represent; otherwise the JSON view says why and stays in charge.
+ * Visual first, JSON as the escape hatch, like the schema editor. Both views edit the same draft
+ * text, and the visual one is offered only while that text holds a document it can represent.
  */
 export function RolePermissionEditor({
 	draft,
diff --git a/src/features/instance/config/roles/editor/RoleVisualEditor.tsx b/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
index 6d6878cc4..7b5a8ba92 100644
--- a/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
+++ b/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
@@ -61,10 +61,8 @@ import {
 const ACTION_LABELS = { read: 'Read', insert: 'Insert', update: 'Update', delete: 'Delete' } as const;
 
 /**
- * The GUI half of the role editor (HarperFast/studio#1634): renders a parsed permission document
- * against the instance schema and reports every edit as the whole next document. Rendering what
- * Harper would enforce, not just what is stored: a table the role does not mention shows as no
- * access, and a scoped table shows each attribute's effective access.
+ * Renders what Harper would enforce, not only what is stored: a table the role does not mention
+ * shows as no access, and a scoped table shows each attribute's effective access.
  */
 export function RoleVisualEditor({
 	permission,
diff --git a/src/features/instance/config/roles/editor/rolePermissionModel.ts b/src/features/instance/config/roles/editor/rolePermissionModel.ts
index 3cd6da4ed..2dffa8524 100644
--- a/src/features/instance/config/roles/editor/rolePermissionModel.ts
+++ b/src/features/instance/config/roles/editor/rolePermissionModel.ts
@@ -17,13 +17,9 @@ import {
 import { compareVersions } from '@/lib/string/wasAReleasedBeforeB';
 
 /**
- * The model behind the visual role editor (HarperFast/studio#1634). The permission JSON stays the
- * single source of truth: the editor reads the parsed document and every edit here is a
- * copy-on-write patch of only the keys it touches, so a key the GUI does not model survives a
- * round-trip by construction rather than by being re-serialized from a model that knows about it.
- *
- * The rules encoded below were traced to Harper 5.3.1 (`validation/role_validation.ts`,
- * `security/permissionsTranslator.js`) and checked against its build.
+ * Every edit here is a copy-on-write patch of only the keys it touches, so content the visual editor
+ * does not model survives a round-trip (see the roles DESIGN.md). Harper rules are traced to 5.3.1's
+ * `validation/role_validation.ts` and `security/permissionsTranslator.js`.
  */
 
 export const TABLE_ACTIONS: readonly LocalRolePermissionAction[] = ['read', 'insert', 'update', 'delete'];
diff --git a/src/features/instance/config/roles/modals/EditRoleModal.test.tsx b/src/features/instance/config/roles/modals/EditRoleModal.test.tsx
index b43484eec..2447aa644 100644
--- a/src/features/instance/config/roles/modals/EditRoleModal.test.tsx
+++ b/src/features/instance/config/roles/modals/EditRoleModal.test.tsx
@@ -16,6 +16,7 @@ const mocks = vi.hoisted(() => ({
 	alterRoleMutate: vi.fn(),
 	schema: {} as InstanceDatabaseMap,
 	describeAllFails: false,
+	registrationFails: false,
 	selfRoleId: 'someone-elses-role',
 }));
 
@@ -56,7 +57,13 @@ vi.mock('@/integrations/api/instance/database/getDescribeAll', () => ({
 vi.mock('@/integrations/api/instance/status/getRegistrationInfo', () => ({
 	getRegistrationInfoQueryOptions: () => ({
 		queryKey: ['test', 'registration_info'],
-		queryFn: () => ({ version: '5.2.2' }),
+		queryFn: () => {
+			if (mocks.registrationFails) {
+				throw new Error('registration_info failed');
+			}
+			return { version: '5.2.2' };
+		},
+		retry: false,
 	}),
 }));
 
@@ -85,6 +92,7 @@ beforeAll(() => {
 beforeEach(() => {
 	mocks.schema = dogSchema;
 	mocks.describeAllFails = false;
+	mocks.registrationFails = false;
 	mocks.selfRoleId = 'someone-elses-role';
 });
 
@@ -281,6 +289,20 @@ describe('EditRoleModal visual editor', () => {
 		expect(save()).toEqual({ data: readOnlyDog([]) });
 	});
 
+	it('without the instance version, will not save a malformed operations value it might drop', async () => {
+		mocks.registrationFails = true;
+		renderModal({ structure_user: true, operations: 'read_only' });
+
+		expect(await screen.findByRole('button', { name: /Retry/ })).toBeTruthy();
+		expect(screen.getByRole('button', { name: 'Save Changes' }).hasAttribute('disabled')).toBe(true);
+		cleanup();
+
+		// A list of names is still saveable: preparePermissionForSave keeps it either way.
+		renderModal({ structure_user: true, operations: ['read_only'] });
+		await screen.findByRole('button', { name: /Retry/ });
+		expect(save()).toEqual({ structure_user: true, operations: ['read_only'] });
+	});
+
 	it('warns when the role changes elsewhere while open, and can load that version', async () => {
 		const { rerenderWith } = renderModal({ data: readOnlyDog([]) });
 		fireEvent.click(await screen.findByRole('checkbox', { name: 'Insert on data.dog' }));

From ac8ecbbbc2bfa82180ac39c04ecda30d9065e82e Mon Sep 17 00:00:00 2001
From: Dawson Toth <dawson@harperdb.io>
Date: Sun, 11 Oct 2026 23:28:44 -0400
Subject: [PATCH 4/7] fix(roles): treat 5.0 prereleases as Harper 5 and warn
 before scoping drops hidden attributes

The cluster user type was offered to new roles on every 5.0.0 prerelease and on
an unparseable version, because the Harper 4 check was "not at least 5.0.0".
It now means a parseable version below 5.0.0-0. Its Harper 4 copy also says
what the flag does grant: describe_all lists every database, table and
attribute for it (harperdb dataLayer/schemaDescribe.js:36). It gets no table
access, since the operations gate and REST short-circuit only on super_user.

Turning attribute scoping on lists only the attributes describe_all shows, so a
computed or relationship attribute loses access at that moment. The unscoped
panel now says so before the switch is flipped, and the model's doc comment no
longer claims access is unchanged. The notInSchema doc comment no longer says
those entries block Save, which no code does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../roles/editor/RoleVisualEditor.test.tsx     | 16 +++++++++++++++-
 .../config/roles/editor/RoleVisualEditor.tsx   | 18 +++++++++++-------
 .../config/roles/editor/rolePermissionModel.ts | 11 +++++++----
 3 files changed, 33 insertions(+), 12 deletions(-)

diff --git a/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx b/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx
index c650c1869..6c2923d8e 100644
--- a/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx
+++ b/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx
@@ -141,13 +141,27 @@ describe('RoleVisualEditor', () => {
 	it('offers the cluster user type on Harper 4, and to a role that already has it', () => {
 		renderEditor({}, '4.7.40');
 		// Harper 4 stores such a user's password reversibly encrypted (harperdb security/user.ts).
-		expect(screen.getByRole('radio', { name: /Cluster user.*recoverable form/ })).toBeTruthy();
+		expect(screen.getByRole('radio', { name: /Cluster user.*list every database.*recoverable form/ })).toBeTruthy();
 		cleanup();
 		renderEditor({ cluster_user: true });
 		const radio = screen.getByRole('radio', { name: /Cluster user.*Harper 5 doesn't use this role type/ });
 		expect(radio.getAttribute('aria-checked')).toBe('true');
 	});
 
+	it.each(['5.0.0-alpha.8', 'not-a-version'])('does not offer the cluster user type to a new role on %s', (version) => {
+		renderEditor({}, version);
+		expect(screen.queryByRole('radio', { name: /Cluster user/ })).toBeNull();
+	});
+
+	it('says before limiting a table that the list may leave out computed and relationship attributes', () => {
+		renderEditor({ data: { tables: { dog: table(true) } } });
+
+		fireEvent.click(screen.getByRole('button', { name: 'Attribute permissions for data.dog' }));
+		expect(screen.getByRole('switch', { name: 'Limit data.dog to specific attributes' }).getAttribute('aria-checked'))
+			.toBe('false');
+		expect(screen.getByText(/can leave out computed and relationship attributes/)).toBeTruthy();
+	});
+
 	it('opens only one database on a role that grants several, so a large schema stays cheap to open', () => {
 		renderEditor({ data: { tables: { dog: table(true) } }, dev: { tables: { thing: table(true) } } });
 
diff --git a/src/features/instance/config/roles/editor/RoleVisualEditor.tsx b/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
index 7b5a8ba92..66adb3a4c 100644
--- a/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
+++ b/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
@@ -6,6 +6,7 @@ import { RadioGroup, RadioGroupItem } from '@/components/ui/radioGroup';
 import { Switch } from '@/components/ui/switch';
 import {
 	ATTRIBUTE_ACTIONS,
+	AttributeView,
 	getAttributeViews,
 	getDatabaseRecord,
 	getEditableDatabaseNames,
@@ -44,7 +45,7 @@ import {
 	withOperations,
 } from '@/integrations/api/localRolePermission';
 import { cn } from '@/lib/cn';
-import { wasAReleasedBeforeB } from '@/lib/string/wasAReleasedBeforeB';
+import { compareVersions } from '@/lib/string/wasAReleasedBeforeB';
 import { ChevronDownIcon, ChevronRightIcon, TriangleAlertIcon } from 'lucide-react';
 import {
 	type ComponentProps,
@@ -191,9 +192,12 @@ function RoleTypeSection({
 }) {
 	const id = useId();
 	// Only Harper 4 gives this flag a meaning: it marks the user clustering connects as, and that user's
-	// password is then stored reversibly encrypted (harperdb security/user.ts). Nothing in Harper 5 reads
-	// it, so it is offered there only to a role that already has it.
-	const harper4 = !wasAReleasedBeforeB('5.0.0', version);
+	// password is then stored reversibly encrypted (harperdb security/user.ts). Its describe_all lists
+	// everything (dataLayer/schemaDescribe.js:36), but it gets no table access: the operations gate and
+	// REST short-circuit only on super_user (utility/operation_authorization.js:370,499,
+	// resources/Table.ts:3643). Nothing in Harper 5 reads it, so it is offered there only to a role that
+	// already has it. A 5.0.0 prerelease is Harper 5; an unparseable version is not taken for Harper 4.
+	const harper4 = compareVersions(version, '0.0.0') >= 0 && compareVersions(version, '5.0.0-0') < 0;
 	const offerClusterUser = roleType === 'cluster_user' || harper4;
 	const dropsOthers = roleType !== 'standard' && carriesOtherPermissions(permission, roleType);
 	return (
@@ -214,7 +218,7 @@ function RoleTypeSection({
 				{offerClusterUser && (
 					<RadioOption id={`${id}-cluster`} value="cluster_user" label="Cluster user">
 						{harper4
-							? 'For the user that connects cluster nodes. Harper keeps the password of a user with this role in a recoverable form so clustering can use it.'
+							? 'For the user that connects cluster nodes. A user with this role can list every database, table and attribute, and Harper keeps its password in a recoverable form so clustering can use it.'
 							: "Harper 5 doesn't use this role type. Harper 4 used it for the user that connects cluster nodes."}
 					</RadioOption>
 				)}
@@ -604,7 +608,7 @@ function AttributePanel({
 }: {
 	label: string;
 	scoped: boolean;
-	views: ReturnType<typeof getAttributeViews>;
+	views: AttributeView[];
 	disabled?: boolean;
 	onScopingChanged: (scoped: boolean) => void;
 	onActionChanged: (attributeName: string, action: (typeof ATTRIBUTE_ACTIONS)[number], value: boolean) => void;
@@ -626,7 +630,7 @@ function AttributePanel({
 			<p className="text-xs text-muted-foreground">
 				{scoped
 					? 'Only the access checked here applies. An attribute with nothing checked has no access, including attributes added to the table later. Computed and relationship attributes may be missing from this list; grant those in the JSON.'
-					: "The table's read, insert and update apply to every attribute."}
+					: "The table's read, insert and update apply to every attribute. Limiting lists only the attributes this instance's schema shows, which can leave out computed and relationship attributes, and those then have no access until granted in the JSON."}
 			</p>
 			{scoped && (
 				<table className="w-full max-w-md text-xs">
diff --git a/src/features/instance/config/roles/editor/rolePermissionModel.ts b/src/features/instance/config/roles/editor/rolePermissionModel.ts
index 2dffa8524..e116e16da 100644
--- a/src/features/instance/config/roles/editor/rolePermissionModel.ts
+++ b/src/features/instance/config/roles/editor/rolePermissionModel.ts
@@ -234,7 +234,9 @@ export interface PreservedEntries {
 /**
  * What the document holds that the visual editor does not render. `notInSchema` is separated
  * because Harper's role validation rejects a role naming a database or table that does not exist
- * (`role_validation.ts` SCHEMA_NOT_FOUND / TABLE_NOT_FOUND), so those block a save until removed.
+ * (`role_validation.ts` SCHEMA_NOT_FOUND / TABLE_NOT_FOUND), so Harper refuses a save until they are
+ * removed. The editor warns and offers to remove them but does not block Save: describe_all is
+ * cached, so a database created a moment ago can read as missing here.
  * Attribute entries the schema does not list are only "not shown": describe_all omits `@computed`
  * attributes unless asked for them, so a missing name may well be a real attribute.
  */
@@ -560,9 +562,10 @@ export function getAttributeViews(
 }
 
 /**
- * Turns attribute scoping on or off for one table. Turning it on lists every attribute with the
- * table's own read/insert/update, so the role's current access does not change at the moment of
- * switching — only attributes added to the table later stay unreadable until granted. Turning it
+ * Turns attribute scoping on or off for one table. Turning it on lists every attribute in
+ * `attributeNames` with the table's own read/insert/update, so their access does not change at the
+ * moment of switching. An attribute describe_all omits (`@computed`, a relationship) is not listed
+ * and loses access until granted in the JSON, as do attributes added to the table later. Turning it
  * off writes `[]`; `restore` brings back a list the author turned off this session, less any action
  * the table has lost since, which role validation would reject on the attribute.
  */

From 9dbcd43ac10d3bd6012afe2bd510b924fa1fd963 Mon Sep 17 00:00:00 2001
From: Dawson Toth <dawson@harperdb.io>
Date: Mon, 12 Oct 2026 10:16:51 -0400
Subject: [PATCH 5/7] fix(roles): stash the structure-user selection when the
 mode changes, not during render
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

StructureUserSection wrote its last-selection ref on every render, which
keeps render impure: a render React discards would still have moved it.
The ref is only read when the mode radio changes, so it is now written
there too, the way OperationsAllowlistEditor stashes its allowlist.

The visual editor tests now render under StrictMode, as main.tsx does,
and pin the Selected → another mode → Selected restore.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../roles/editor/RoleVisualEditor.test.tsx    | 26 ++++++++++++++++---
 .../config/roles/editor/RoleVisualEditor.tsx  |  6 ++---
 2 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx b/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx
index 6c2923d8e..80cafcca5 100644
--- a/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx
+++ b/src/features/instance/config/roles/editor/RoleVisualEditor.test.tsx
@@ -5,7 +5,7 @@ import { getTableEntry } from '@/features/instance/config/roles/editor/rolePermi
 import { RoleVisualEditor } from '@/features/instance/config/roles/editor/RoleVisualEditor';
 import { InstanceDatabaseMap, LocalRolePermission } from '@/integrations/api/api.patch';
 import { cleanup, fireEvent, render, screen } from '@testing-library/react';
-import { useState } from 'react';
+import { StrictMode, useState } from 'react';
 import { afterEach, beforeAll, describe, expect, it } from 'vitest';
 
 const schema = {
@@ -31,7 +31,7 @@ beforeAll(() => {
 
 afterEach(cleanup);
 
-/** Holds the document like the modal does, and exposes the latest one to the test. */
+/** Holds the document like the modal does, and exposes the latest one to the test. StrictMode as in main.tsx. */
 function renderEditor(initial: unknown, version = '5.3.1') {
 	const latest = { current: initial as LocalRolePermission };
 	function Harness() {
@@ -48,7 +48,11 @@ function renderEditor(initial: unknown, version = '5.3.1') {
 			/>
 		);
 	}
-	render(<Harness />);
+	render(
+		<StrictMode>
+			<Harness />
+		</StrictMode>,
+	);
 	return latest;
 }
 
@@ -138,6 +142,22 @@ describe('RoleVisualEditor', () => {
 		expect(screen.queryByRole('checkbox', { name: 'Read on data.dog' })).toBeNull();
 	});
 
+	it('restores the selected databases after switching structure_user to another mode and back', () => {
+		const latest = renderEditor({ structure_user: ['data'], data: { tables: {} } });
+
+		fireEvent.click(screen.getByRole('radio', { name: /All databases/ }));
+		expect(latest.current.structure_user).toBe(true);
+		fireEvent.click(screen.getByRole('radio', { name: /^No/ }));
+		expect(latest.current.structure_user).toBe(false);
+		fireEvent.click(screen.getByRole('radio', { name: /Selected databases/ }));
+		expect(latest.current.structure_user).toEqual(['data']);
+
+		fireEvent.click(checkbox('Structure user on dev'));
+		fireEvent.click(screen.getByRole('radio', { name: /All databases/ }));
+		fireEvent.click(screen.getByRole('radio', { name: /Selected databases/ }));
+		expect(latest.current.structure_user).toEqual(['data', 'dev']);
+	});
+
 	it('offers the cluster user type on Harper 4, and to a role that already has it', () => {
 		renderEditor({}, '4.7.40');
 		// Harper 4 stores such a user's password reversibly encrypted (harperdb security/user.ts).
diff --git a/src/features/instance/config/roles/editor/RoleVisualEditor.tsx b/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
index 66adb3a4c..c5622c531 100644
--- a/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
+++ b/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
@@ -263,13 +263,13 @@ function StructureUserSection({
 	const selected = Array.isArray(structureUser) ? structureUser : [];
 	// Lets "Selected databases" → another mode → back restore the picks instead of starting empty.
 	const lastSelectionRef = useRef<string[]>(selected);
-	if (Array.isArray(structureUser)) {
-		lastSelectionRef.current = structureUser;
-	}
 	const listed = [...databaseNames, ...selected.filter((name) => !databaseNames.includes(name))];
 	const hasTablePermissions = Object.keys(permission).some((key) => !RESERVED_PERMISSION_KEYS.has(key));
 
 	const onModeChange = (next: string) => {
+		if (Array.isArray(structureUser)) {
+			lastSelectionRef.current = structureUser;
+		}
 		onChange(
 			setStructureUser(permission, next === 'all' ? true : next === 'selected' ? lastSelectionRef.current : false),
 		);

From dfedb1bc783453ca815e8393cf68b3ac99264a8c Mon Sep 17 00:00:00 2001
From: Dawson Toth <dawson@harperdb.io>
Date: Mon, 12 Oct 2026 10:21:18 -0400
Subject: [PATCH 6/7] fix(roles): point the table grid's updater at the
 committed document, not the rendered one

TablePermissionsSection refreshed latestRef during render, so a render
React discards could leave the shared updater patching a document that
never reached the screen. It is now refreshed in a layout effect, which
runs before the browser can deliver the next click. The scoping-restore
map is passed down as its ref and read only in the toggle handler, so
render no longer reads a ref at all.

`update` and the ref stay stable, so the memoized rows still bail out:
on a 500-table database each click re-renders exactly one TableRows,
before and after (median ~3ms per click in jsdom either way).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../config/roles/editor/RoleVisualEditor.tsx     | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/src/features/instance/config/roles/editor/RoleVisualEditor.tsx b/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
index c5622c531..f557d1ea2 100644
--- a/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
+++ b/src/features/instance/config/roles/editor/RoleVisualEditor.tsx
@@ -51,6 +51,7 @@ import {
 	type ComponentProps,
 	Fragment,
 	memo,
+	type RefObject,
 	useCallback,
 	useId,
 	useLayoutEffect,
@@ -328,6 +329,7 @@ function StructureUserSection({
 }
 
 type PermissionPatch = (permission: LocalRolePermission) => LocalRolePermission;
+type ScopingRestore = RefObject<Map<string, LocalRoleAttributePermissionTable[]>>;
 
 function TablePermissionsSection({
 	permission,
@@ -361,7 +363,9 @@ function TablePermissionsSection({
 	// One stable updater for every row, applied to the latest document: rows are memoized on their
 	// own database record, so on a large schema an edit re-renders only the database it touched.
 	const latestRef = useRef({ permission, onChange });
-	latestRef.current = { permission, onChange };
+	useLayoutEffect(() => {
+		latestRef.current = { permission, onChange };
+	}, [permission, onChange]);
 	const update = useCallback((patch: PermissionPatch) => {
 		latestRef.current.onChange(patch(latestRef.current.permission));
 	}, []);
@@ -383,7 +387,7 @@ function TablePermissionsSection({
 						structureScoped={structureDatabases.includes(databaseName)}
 						readOnly={readOnly}
 						update={update}
-						scopingRestore={scopingRestoreRef.current}
+						scopingRestore={scopingRestoreRef}
 					/>
 				))}
 			</Accordion>
@@ -406,7 +410,7 @@ const DatabaseSection = memo(function DatabaseSection({
 	structureScoped: boolean;
 	readOnly?: boolean;
 	update: (patch: PermissionPatch) => void;
-	scopingRestore: Map<string, LocalRoleAttributePermissionTable[]>;
+	scopingRestore: ScopingRestore;
 }) {
 	const tableNames = Object.keys(tables);
 	const entries = tableNames.map((tableName) => getTableEntryInRecord(record, tableName));
@@ -511,7 +515,7 @@ const TableRows = memo(function TableRows({
 	entry: LocalRolePermissionTable | undefined;
 	readOnly?: boolean;
 	update: (patch: PermissionPatch) => void;
-	scopingRestore: Map<string, LocalRoleAttributePermissionTable[]>;
+	scopingRestore: ScopingRestore;
 }) {
 	const attributeNames = useMemo(() => getTableAttributeNames(schemaTable), [schemaTable]);
 	const primaryKey = getTablePrimaryKey(schemaTable);
@@ -524,7 +528,7 @@ const TableRows = memo(function TableRows({
 
 	const onScopingChanged = (next: boolean) => {
 		if (!next && entry?.attribute_permissions) {
-			scopingRestore.set(restoreKey, entry.attribute_permissions);
+			scopingRestore.current.set(restoreKey, entry.attribute_permissions);
 		}
 		update((permission) =>
 			setAttributeScoping(
@@ -533,7 +537,7 @@ const TableRows = memo(function TableRows({
 				tableName,
 				next,
 				attributeNames,
-				next ? scopingRestore.get(restoreKey) : undefined,
+				next ? scopingRestore.current.get(restoreKey) : undefined,
 			)
 		);
 	};

From d9c3134520cc3160543a1079bc8d3f0ebf43e05c Mon Sep 17 00:00:00 2001
From: Dawson Toth <dawson@harperdb.io>
Date: Mon, 12 Oct 2026 10:24:06 -0400
Subject: [PATCH 7/7] test(roles): pin that the role editor picks its first
 view once, under StrictMode

RolePermissionEditor decides between the visual and JSON views during the
first render that has the schema, guarded so it fires once per mount.
Both modal suites now render under StrictMode, as main.tsx does, so that
decision runs through React's double render in every modal test.

A new case pins what the guard is for: a role that opened in the JSON
view stays there after the author fixes it, until they choose the visual
editor. Deriving the view from availability instead fails it, because
the editor unmounts mid-edit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../config/roles/modals/AddRoleModal.test.tsx |  9 ++++--
 .../roles/modals/EditRoleModal.test.tsx       | 29 +++++++++++++++----
 2 files changed, 29 insertions(+), 9 deletions(-)

diff --git a/src/features/instance/config/roles/modals/AddRoleModal.test.tsx b/src/features/instance/config/roles/modals/AddRoleModal.test.tsx
index 59f0b46ee..3c5dc8865 100644
--- a/src/features/instance/config/roles/modals/AddRoleModal.test.tsx
+++ b/src/features/instance/config/roles/modals/AddRoleModal.test.tsx
@@ -4,6 +4,7 @@
 import { AddRoleModal } from '@/features/instance/config/roles/modals/AddRoleModal';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { StrictMode } from 'react';
 import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
 
 const { addRoleMutate } = vi.hoisted(() => ({ addRoleMutate: vi.fn() }));
@@ -53,9 +54,11 @@ afterEach(() => {
 function renderModal() {
 	const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
 	render(
-		<QueryClientProvider client={queryClient}>
-			<AddRoleModal onChangesSaved={() => {}} closeModal={() => {}} />
-		</QueryClientProvider>,
+		<StrictMode>
+			<QueryClientProvider client={queryClient}>
+				<AddRoleModal onChangesSaved={() => {}} closeModal={() => {}} />
+			</QueryClientProvider>
+		</StrictMode>,
 	);
 }
 
diff --git a/src/features/instance/config/roles/modals/EditRoleModal.test.tsx b/src/features/instance/config/roles/modals/EditRoleModal.test.tsx
index 2447aa644..69207e06f 100644
--- a/src/features/instance/config/roles/modals/EditRoleModal.test.tsx
+++ b/src/features/instance/config/roles/modals/EditRoleModal.test.tsx
@@ -5,6 +5,7 @@ import { EditRoleModal } from '@/features/instance/config/roles/modals/EditRoleM
 import { InstanceDatabaseMap, LocalRole } from '@/integrations/api/api.patch';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { StrictMode } from 'react';
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 
 /*
@@ -123,14 +124,16 @@ function modal(data: LocalRole) {
 	);
 }
 
+/** StrictMode as in main.tsx, so every render-phase decision is also exercised twice. */
 function renderModal(permission: unknown) {
 	const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
-	const result = render(<QueryClientProvider client={queryClient}>{modal(roleData(permission))}</QueryClientProvider>);
-	return {
-		...result,
-		rerenderWith: (data: LocalRole) =>
-			result.rerender(<QueryClientProvider client={queryClient}>{modal(data)}</QueryClientProvider>),
-	};
+	const tree = (data: LocalRole) => (
+		<StrictMode>
+			<QueryClientProvider client={queryClient}>{modal(data)}</QueryClientProvider>
+		</StrictMode>
+	);
+	const result = render(tree(roleData(permission)));
+	return { ...result, rerenderWith: (data: LocalRole) => result.rerender(tree(data)) };
 }
 
 function save() {
@@ -253,6 +256,20 @@ describe('EditRoleModal visual editor', () => {
 		expect(screen.queryByRole('checkbox', { name: 'Read on data.dog' })).toBeNull();
 	});
 
+	it('stays in the JSON view once the author fixes it, until they choose the visual editor', async () => {
+		renderModal({ data: { tables: { dog: { read: 1 } } } });
+
+		const editor = await screen.findByRole('textbox', { name: 'Role permission JSON' }) as HTMLTextAreaElement;
+		fireEvent.change(editor, { target: { value: JSON.stringify({ data: readOnlyDog([]) }) } });
+		// Switching on its own would unmount the editor under the author's cursor.
+		expect(screen.getByRole('textbox', { name: 'Role permission JSON' })).toBe(editor);
+		const visual = screen.getByRole('button', { name: /Visual editor/ });
+		expect(visual.hasAttribute('disabled')).toBe(false);
+
+		fireEvent.click(visual);
+		expect((screen.getByRole('checkbox', { name: 'Read on data.dog' }) as HTMLInputElement).checked).toBe(true);
+	});
+
 	it('hides per-table permissions for a structure user of every database and drops them on save', async () => {
 		renderModal({ data: readOnlyDog([]) });