docs(spec): mark feature-absent security props EXPERIMENTAL — Policy, SharingRule, flow runAs (ADR-0049) (#1902)

Completes the pre-MVP "stop the spec from promising what it doesn't enforce"
sweep of the #1878 P0 cluster. These three name security boundaries but have no
runtime enforcement and the underlying feature does not exist yet, so per
ADR-0049 they are explicitly marked `[EXPERIMENTAL — not enforced]` rather than
left silently dead. No behaviour change; enforcement is deferred to M2.

- PolicySchema (#1882): not registered, no consumer; better-auth runs hardcoded
  defaults. Schema-level warning + name field annotated.
- SharingRuleSchema (#1887): live engine uses a divergent `sys_sharing_rule`
  model; spec CEL `condition` is never compiled. Schema-level warning.
- flow `runAs` (#1888): service-automation engine ignores it (no identity
  switch). Field annotated.

Refs #1878 #1882 #1887 #1888

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

packages/spec/src/automation/flow.zod.ts

@@ -247,7 +247,11 @@ export const FlowSchema = lazySchema(() => z.object({
 
   /** Execution Config */
   active: z.boolean().default(false).describe('Is active (Deprecated: use status)'),
-  runAs: z.enum(['system', 'user']).default('user').describe('Execution context'),
+  // ⚠️ EXPERIMENTAL — NOT ENFORCED (ADR-0049, #1888). The service-automation
+  // engine ignores `runAs`: a flow declaring `runAs: system` does not elevate,
+  // and `user` does not de-elevate — steps run as the triggering context's
+  // identity regardless. Identity switching is tracked by #1888 (M2).
+  runAs: z.enum(['system', 'user']).default('user').describe('[EXPERIMENTAL — not enforced] Execution context'),
 
   /** Error Handling Strategy */
   errorHandling: z.object({

packages/spec/src/security/policy.zod.ts

@@ -46,9 +46,18 @@ export const AuditPolicySchema = lazySchema(() => z.object({
 /**
  * Security Policy Schema
  * "The Cloud Compliance Contract"
+ *
+ * ⚠️ EXPERIMENTAL — NOT ENFORCED (ADR-0049, #1882).
+ * This schema is currently a no-op: it is not registered as a metadata type and
+ * has no runtime consumer. Password complexity, session idle/absolute timeout,
+ * `forceMfa`, the IP allow-list (`trustedRanges`/`vpnRequired`) and audit
+ * retention/redaction are all parsed but enforced by nothing — `better-auth`
+ * runs hardcoded defaults regardless. Authoring a policy here does NOT change
+ * behaviour. Treat as a forward-looking contract only; do not rely on it for
+ * compliance. Enforcement (or removal) is tracked by #1882 for M2.
  */
 export const PolicySchema = lazySchema(() => z.object({
-  name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Policy Name'),
+  name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('[EXPERIMENTAL — not enforced] Policy Name'),
 
   password: PasswordPolicySchema.optional(),
   network: NetworkPolicySchema.optional(),

packages/spec/src/security/sharing.zod.ts

@@ -93,6 +93,14 @@ export const OwnerSharingRuleSchema = lazySchema(() => BaseSharingRuleSchema.ext
 
 /**
  * Master Sharing Rule Schema
+ *
+ * ⚠️ EXPERIMENTAL — NOT ENFORCED as authored (ADR-0049, #1887).
+ * The live engine enforces a divergent runtime model (`sys_sharing_rule`: JSON
+ * `criteria_json`, recipient enum `user`/`team`/`department`/`role`/`queue`).
+ * This spec's CEL `condition` is never compiled (unparsable CEL degrades to
+ * "match nothing"), and recipients such as `role_and_subordinates`/`guest` have
+ * no runtime mapping. Authoring a rule via this schema does NOT grant access —
+ * use `sys_sharing_rule` directly until reconciliation. Tracked by #1887 (M2).
  */
 export const SharingRuleSchema = lazySchema(() => z.discriminatedUnion('type', [
   CriteriaSharingRuleSchema,