refactor(spec): remove dead compliance subsystems (ADR-0056 D8) + mark agent visibility EXPERIMENTAL (#1901)

.changeset/remove-dead-compliance-subsystems.md

@@ -0,0 +1,36 @@
+---
+'@objectstack/spec': minor
+---
+
+BREAKING (pre-launch): remove the three declared-but-never-enforced compliance
+subsystems per ADR-0056 D8 ("design + enforce, or remove"), and mark the AI
+agent `visibility` property EXPERIMENTAL (#1901).
+
+Removed — none of these were read by any runtime path, and compliance-grade
+configuration must never merely look live:
+
+- `ComplianceConfigSchema` / `GDPRConfigSchema` / `HIPAAConfigSchema` (and the
+  rest of `system/compliance.zod.ts`) — there is no data-subject-rights engine,
+  retention enforcer, or BAA gate. FROM `import { ComplianceConfigSchema } from
+  '@objectstack/spec/system'` TO: delete the reference — a real compliance
+  subsystem will be designed top-down when scheduled.
+- `MaskingConfigSchema` / `MaskingRuleSchema` (`system/masking.zod.ts`) — no
+  redaction layer applies them. FROM masking config TO: field-level security
+  (permission-set field rules, enforced by plugin-security's field masker); a
+  subtractive masking/deny layer arrives with ADR-0066 ⑦/⑧ if needed.
+- `RLSConfigSchema` / `RLSAuditEventSchema` / `RLSAuditConfigSchema`
+  (`security/rls.zod.ts`) — the enforced RLS path never read the global config.
+  FROM global `RLSConfig` TO: per-policy `RowLevelSecurityPolicySchema` (the
+  live, enforced surface — unchanged).
+
+Kept, still `[EXPERIMENTAL]`: `EncryptionConfigSchema` (at-rest field
+encryption) — a real enterprise roadmap item with a stable shape; carrying it
+marked costs less than remove-and-re-add (ADR-0087).
+
+Marked `[EXPERIMENTAL — NOT ENFORCED]` (#1901): `AgentSchema.visibility` — the
+chat-access evaluator deliberately excludes it and the agent list route does
+not filter by it, so `private` does not hide an agent. The schema description
+and the authoring form now say so; use `access` / `permissions` (both enforced
+at the chat route since #1884) for real gating. The ADR-0056 D10 conformance
+matrix tracks all dispositions (`agent-visibility` experimental;
+`compliance-configs` / `data-masking` / `rls-config-global` removed).

content/docs/permissions/authorization.mdx

@@ -143,7 +143,7 @@ one of two doors, each writing only what it owns:
 | 2 · Distribution / install / upgrade / uninstall | Install-consent scopes (ADR-0025 — consent ≠ RBAC grants); namespaced, collision-free composition; provenance axis makes uninstall well-defined | ADR-0025/0028/0048/0086 |
 | 3 · Environment composition / assignment | Platform-owned assignment records (`sys_user_role` etc.); anti-escalation; union semantics | ADR-0057 D4 |
 | 4 · Runtime enforcement | The six-gate chain above; ~18 primitives enforced and CI-guarded | ADR-0056 D10 matrix |
-| 5 · Production / enterprise | Honest `[EXPERIMENTAL]` markers on the unenforced surface (field encryption, masking, compliance configs); enterprise authentication hardening staged per ADR-0069 | ADR-0049/0056 D8, ADR-0069 |
+| 5 · Production / enterprise | ADR-0056 D8 dispositions settled (2026-07): compliance configs, data masking, and the global RLSConfig were **removed** (never enforced); field encryption stays honestly `[EXPERIMENTAL]` (roadmap); agent `visibility` is marked `[EXPERIMENTAL]` pending #1901. Enterprise authentication hardening staged per ADR-0069 | ADR-0049/0056 D8, ADR-0069 |
 
 ## Governance: how "declared = enforced" is kept true
 

content/docs/protocol/objectql/security.mdx

@@ -198,7 +198,7 @@ rowLevelSecurity:
     using: "status == 'active'"  # date-window/function predicates (NOW(), arithmetic) are NOT pushdown-able (ADR-0055) — enforce time windows in the app layer or a pre-resolved set
 ```
 
-> RLS conditions are compiled to parameterized queries. The default policy when no rule matches is **deny** (`RLSConfigSchema.defaultPolicy`).
+> RLS conditions are compiled to parameterized queries, and the enforcement path fails **closed**: an applicable policy that cannot be compiled denies (returns zero rows) rather than being dropped. (The old global `RLSConfigSchema` was removed in 2026-07 — it was never read by the enforced path; per-policy `RowLevelSecurityPolicySchema` is the live surface.)
 
 ---
 
@@ -251,71 +251,14 @@ fields:
 
 ## 4. Data Masking
 
-> **Status: schema exists, field wiring removed.** `MaskingRuleSchema`
-> (`packages/spec/src/system/masking.zod.ts`, strategies `redact`, `partial`,
-> `hash`, `tokenize`, `randomize`, `nullify`, `substitute`) remains in the
-> System namespace, but the per-field `maskingRule` property was **pruned from
-> the Field schema in 2026-06** as dead surface — it was never read by the
-> runtime (see `docs/audits/2026-06-dead-surface-disposition-plan.md`). To keep
-> a value out of reader hands today, use FLS (`readable: false`), `hidden`, or
-> a `type: 'secret'` field. The examples below show the *schema shapes* for
-> implementers, not a wired runtime capability.
-
-### Partial Masking
-
-```yaml
-# user.object.yml
-fields:
-  ssn:
-    type: text
-    label: SSN
-    maskingRule:
-      field: ssn
-      strategy: partial
-      pattern: '\d{5}$'        # regex selecting the visible portion
-      preserveFormat: true
-      preserveLength: true
-      exemptRoles: [hr_admin]  # roles that see the unmasked value
-```
-
-### Full Redaction
-
-```yaml
-fields:
-  credit_card:
-    type: text
-    label: Credit Card
-    maskingRule:
-      field: credit_card
-      strategy: redact
-```
-
-### Role-Scoped Masking
-
-`roles` lists the roles that see the *masked* value; `exemptRoles` lists those that see the original:
-
-```yaml
-fields:
-  salary:
-    type: currency
-    label: Salary
-    maskingRule:
-      field: salary
-      strategy: partial
-      exemptRoles: [hr_manager, hr_admin]
-```
-
-### Hash Masking
-
-```yaml
-fields:
-  email:
-    type: email
-    label: Email
-    maskingRule:
-      field: email
-      strategy: hash
-```
+> **Status: REMOVED (2026-07, ADR-0056 D8 "design + enforce, or remove").**
+> `MaskingRuleSchema` / `MaskingConfigSchema` were deleted from the spec: no
+> redaction layer ever applied them, and the per-field `maskingRule` property
+> had already been pruned in 2026-06. To keep a value out of reader hands, use
+> **FLS** (`readable: false` field permissions — enforced by plugin-security's
+> field masker), `hidden`, or a `type: 'secret'` field. A subtractive
+> masking/deny layer, if needed, arrives with the ADR-0066 ⑦/⑧ muting work.
+> Disposition tracked in the ADR-0056 D10 conformance matrix (`data-masking`).
 
 ---
 
@@ -421,7 +364,7 @@ Object- and field-level history is opt-in metadata, not a free-form `enable.audi
 
 - **Field history** — set `trackHistory: true` on the object (`ObjectCapabilities` in `object.zod.ts`) to record per-field changes.
 - **Per-field audit trail** — set `auditTrail: true` on an individual field to track every change with user and timestamp.
-- **RLS audit** — RLS policy evaluations can be logged via `RLSAuditConfigSchema` (`enabled`, `logLevel`, `destination`, `retentionDays`, …). The recorded event shape is `RLSAuditEventSchema` (timestamp, userId, operation, object, policyName, granted, evaluationDurationMs).
+- **RLS audit** — removed (2026-07, ADR-0056 D8): the `RLSAuditConfigSchema`/`RLSAuditEventSchema` shapes were never emitted or read by the runtime RLS path and were deleted from the spec. Enforcement decisions surface today through the security plugin's fail-closed warnings and the standard audit log (`plugin-audit`), not a dedicated RLS event stream.
 
 ```yaml
 # account.object.yml

content/docs/protocol/objectql/types.mdx

@@ -950,9 +950,10 @@ api_key:
 
 > The per-field `maskingRule` and `encryptionConfig` properties were **pruned
 > from the Field schema in 2026-06** — they were declared surface with no
-> runtime consumer. The `MaskingRuleSchema`/`EncryptionConfigSchema` shapes
-> remain in the System namespace for implementers; see
-> [Security & Access Control](/docs/protocol/objectql/security) for their status.
+> runtime consumer. In 2026-07 the masking shapes were removed from the spec
+> entirely (ADR-0056 D8); `EncryptionConfigSchema` remains in the System
+> namespace as `[EXPERIMENTAL]` roadmap surface. See
+> [Security & Access Control](/docs/protocol/objectql/security) for status.
 
 ## Type Selection Guide
 

content/docs/references/ai/agent.mdx

@@ -84,7 +84,7 @@ const result = AIKnowledge.parse(data);
 | **access** | `string[]` | optional | Who can chat with this agent |
 | **permissions** | `string[]` | optional | Required permissions or roles |
 | **tenantId** | `string` | optional | Tenant/Organization ID |
-| **visibility** | `Enum<'global' \| 'organization' \| 'private'>` | ✅ |  |
+| **visibility** | `Enum<'global' \| 'organization' \| 'private'>` | ✅ | [EXPERIMENTAL — NOT ENFORCED, #1901] Intended listing scope. No runtime consumer yet; use access/permissions for real gating. |
 | **planning** | `Object` | optional | Autonomous reasoning and planning configuration |
 | **memory** | `Object` | optional | Agent memory management |
 | **guardrails** | `Object` | optional | Safety guardrails for the agent |

content/docs/references/cloud/app-store.mdx

@@ -21,9 +21,10 @@ installing, and managing marketplace apps from within ObjectOS.
 
 ## Customer Journey
 
-```mermaid
-flowchart LR
-    Discover --> Evaluate --> Install --> Configure --> Use --> Rate["Rate / Review"] --> Manage
+```
+
+Discover → Evaluate → Install → Configure → Use → Rate/Review → Manage
+
 ```
 
 ## Key Concepts

content/docs/references/cloud/developer-portal.mdx

@@ -11,9 +11,10 @@ Defines schemas for the developer-facing side of the marketplace ecosystem.
 
 Covers the complete developer journey:
 
-```mermaid
-flowchart LR
-    Register --> Create["Create App"] --> Develop --> Validate --> Build --> Submit --> Monitor --> Iterate
+```
+
+Register → Create App → Develop → Validate → Build → Submit → Monitor → Iterate
+
 ```
 
 ## Architecture Alignment

content/docs/references/cloud/marketplace.mdx

@@ -47,12 +47,18 @@ platform, and customers who install plugins.
 
 ## Platform Management Flow
 
-```mermaid
-flowchart LR
-    A["1 · Receive<br/>accept submissions from verified publishers"] --> B["2 · Scan<br/>automated security + compatibility check"]
-    B --> C["3 · Review<br/>human review for quality + policy"]
-    C --> D["4 · Catalog<br/>index in marketplace search"]
-    D --> E["5 · Monitor<br/>track installs, ratings, issues, SLAs"]
+```
+
+1. Receive   → Accept submissions from verified publishers
+
+2. Scan      → Automated security scan and compatibility check
+
+3. Review    → Human review for quality and policy compliance
+
+4. Catalog   → Index in marketplace search catalog
+
+5. Monitor   → Track installs, ratings, issues, and enforce SLAs
+
 ```
 
 <Callout type="info">

content/docs/references/data/field.mdx

@@ -14,8 +14,8 @@ Field Type Enum
 ## TypeScript Usage
 
 ```typescript
-import { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, FieldType, FileAttachmentConfig, LocationCoordinates, SelectOption, VectorConfig } from '@objectstack/spec/data';
-import type { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, FieldType, FileAttachmentConfig, LocationCoordinates, SelectOption, VectorConfig } from '@objectstack/spec/data';
+import { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, FieldType, FileAttachmentConfig, LocationCoordinates, VectorConfig } from '@objectstack/spec/data';
+import type { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, FieldType, FileAttachmentConfig, LocationCoordinates, VectorConfig } from '@objectstack/spec/data';
 
 // Validate data
 const result = Address.parse(data);
@@ -194,20 +194,6 @@ const result = Address.parse(data);
 | **accuracy** | `number` | optional | Accuracy in meters |
 
 
----
-
-## SelectOption
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **label** | `string` | ✅ | Display label (human-readable, any case allowed) |
-| **value** | `string` | ✅ | Stored value (lowercase machine identifier) |
-| **color** | `string` | optional | Color code for badges/charts |
-| **default** | `boolean` | optional | Is default option |
-
-
 ---
 
 ## VectorConfig

content/docs/references/data/object.mdx

@@ -14,8 +14,8 @@ API Operations Enum
 ## TypeScript Usage
 
 ```typescript
-import { ApiMethod, Index, ObjectAccessConfig, ObjectCapabilities, ObjectExternalBinding, ObjectFieldGroup, ObjectOwnershipEnum, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data';
-import type { ApiMethod, Index, ObjectAccessConfig, ObjectCapabilities, ObjectExternalBinding, ObjectFieldGroup, ObjectOwnershipEnum, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data';
+import { ApiMethod, Index, ObjectAccessConfig, ObjectCapabilities, ObjectExternalBinding, ObjectFieldGroup, ObjectOwnershipEnum, ObjectRequiredPermissions, PerOperationRequiredPermissions, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data';
+import type { ApiMethod, Index, ObjectAccessConfig, ObjectCapabilities, ObjectExternalBinding, ObjectFieldGroup, ObjectOwnershipEnum, ObjectRequiredPermissions, PerOperationRequiredPermissions, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data';
 
 // Validate data
 const result = ApiMethod.parse(data);
@@ -135,6 +135,48 @@ External datasource binding (ADR-0015)
 * `extend`
 
 
+---
+
+## ObjectRequiredPermissions
+
+### Union Options
+
+This schema accepts one of the following structures:
+
+#### Option 1
+
+Type: `string[]`
+
+---
+
+#### Option 2
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **read** | `string[]` | optional | Capabilities required to read (find/findOne/count/aggregate). |
+| **create** | `string[]` | optional | Capabilities required to create (insert). |
+| **update** | `string[]` | optional | Capabilities required to update (update/transfer/restore). |
+| **delete** | `string[]` | optional | Capabilities required to delete (delete/purge). |
+
+---
+
+
+---
+
+## PerOperationRequiredPermissions
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **read** | `string[]` | optional | Capabilities required to read (find/findOne/count/aggregate). |
+| **create** | `string[]` | optional | Capabilities required to create (insert). |
+| **update** | `string[]` | optional | Capabilities required to update (update/transfer/restore). |
+| **delete** | `string[]` | optional | Capabilities required to delete (delete/purge). |
+
+
 ---
 
 ## SoftDeleteConfig

content/docs/references/data/seed-loader.mdx

@@ -21,13 +21,20 @@ relationship resolution, dependency ordering, and multi-pass insertion.
 
 ## Loading Flow
 
-```mermaid
-flowchart TD
-    A["1 · Build object dependency graph<br/>from field metadata (lookup / master_detail)"] --> B["2 · Topological sort<br/>→ insert order (parents before children)"]
-    B --> C["3 · Pass 1 — insert/upsert records,<br/>resolve references via externalId"]
-    C --> D["4 · Pass 2 — fill deferred references<br/>(circular / delayed dependencies)"]
-    D --> E["5 · Validate & report unresolved references"]
-    E --> F["6 · Return structured result<br/>with per-object stats"]
+```
+
+1. Build object dependency graph from field metadata (lookup/master_detail)
+
+2. Topological sort → determine insert order (parents before children)
+
+3. Pass 1: Insert/upsert records, resolve references via externalId
+
+4. Pass 2: Fill deferred references (circular/delayed dependencies)
+
+5. Validate & report unresolved references
+
+6. Return structured result with per-object stats
+
 ```
 
 <Callout type="info">

content/docs/references/kernel/execution-context.mdx

@@ -61,6 +61,7 @@ const result = ExecutionContext.parse(data);
 | **org_user_ids** | `string[]` | optional |  |
 | **rlsMembership** | `Record<string, string[]>` | optional |  |
 | **isSystem** | `boolean` | ✅ |  |
+| **skipTriggers** | `boolean` | optional |  |
 | **accessToken** | `string` | optional |  |
 | **transaction** | `any` | optional |  |
 | **traceId** | `string` | optional |  |

content/docs/references/kernel/package-upgrade.mdx

@@ -25,13 +25,20 @@ and rollback capabilities.
 
 ## Upgrade Flow
 
-```mermaid
-flowchart LR
-    A["1 · PreCheck<br/>validate compatibility, deps"] --> B["2 · Plan<br/>upgrade plan + metadata diff"]
-    B --> C["3 · Snapshot<br/>backup metadata + customizations"]
-    C --> D["4 · Execute<br/>apply new metadata (3-way merge)"]
-    D --> E["5 · Validate<br/>post-upgrade health checks"]
-    E --> F["6 · Commit<br/>finalize (or Rollback on failure)"]
+```
+
+1. PreCheck    → Validate compatibility, check dependencies
+
+2. Plan        → Generate upgrade plan with metadata diff
+
+3. Snapshot    → Backup current state (metadata + customizations)
+
+4. Execute     → Apply new package metadata with 3-way merge
+
+5. Validate    → Run post-upgrade health checks
+
+6. Commit      → Finalize upgrade (or Rollback on failure)
+
 ```
 
 <Callout type="info">