@objectstack/spec 5.0.0 → 5.2.0

package/dist/kernel/index.js

@@ -83,6 +83,163 @@ var OclifPluginConfigSchema = lazySchema(() => zod.z.object({
   /** Topic separator character (default: space) */
   topicSeparator: zod.z.string().optional().describe("Character separating topic and command names")
 }).describe("oclif plugin configuration section"));
+var EventScopeSchema = zod.z.enum(["local", "cluster", "tenant"]).describe("Where the event must be delivered: local process, whole cluster, or tenant-scoped.");
+var EventDeliverySemanticsSchema = zod.z.enum([
+  "best-effort",
+  "at-least-once",
+  "exactly-once"
+]).describe("Delivery guarantee offered by the transport.");
+var EventClusterOptionsSchema = lazySchema(() => zod.z.object({
+  /**
+   * Where the event must be delivered.
+   * @default 'local'
+   */
+  scope: EventScopeSchema.optional().default("local").describe("Delivery scope. Default `local` for backward compatibility."),
+  /**
+   * Delivery guarantee. For `local` scope the default is `best-effort`;
+   * for `cluster` / `tenant` scopes the runtime upgrades the default to
+   * `at-least-once` if the field is omitted.
+   */
+  deliverySemantics: EventDeliverySemanticsSchema.optional().describe("Delivery guarantee. Default depends on scope."),
+  /**
+   * Partition key for ordered delivery. Two events with the same
+   * `partitionKey` are delivered to handlers in emit order even when
+   * multiple consumers run in parallel. Different keys may interleave.
+   *
+   * Typical values: record id, tenant id, conversation id.
+   */
+  partitionKey: zod.z.string().min(1).optional().describe("Stable key that guarantees emit-order delivery for same-key events.")
+}).describe("Per-emit cluster routing & ordering options."));
+var ServiceClusterScopeSchema = zod.z.enum(["node", "cluster"]).describe("Whether this service runs on every node or as a cluster singleton.");
+var ServiceLeaderStrategySchema = zod.z.enum([
+  "leader-elected",
+  "partitioned",
+  "idempotent-broadcast"
+]).describe("How the cluster-singleton invariant is enforced at runtime.");
+var ServiceClusterAnnotationsSchema = lazySchema(() => zod.z.object({
+  /**
+   * Where the service runs in a cluster.
+   * @default 'node'
+   */
+  clusterScope: ServiceClusterScopeSchema.optional().default("node").describe("Per-node vs cluster-singleton presence."),
+  /**
+   * Required when `clusterScope === 'cluster'`. Ignored otherwise.
+   * Validation of this requirement is performed at runtime by the kernel,
+   * not at parse time, so that legacy registrations without the field
+   * continue to parse cleanly.
+   */
+  leaderStrategy: ServiceLeaderStrategySchema.optional().describe("How the cluster-singleton invariant is maintained."),
+  /**
+   * Optional cluster-wide identifier for the service. Defaults to the
+   * service `name`. Set this when two physically different services need
+   * to share the same leadership lock (e.g. for safe rolling upgrades).
+   */
+  clusterId: zod.z.string().min(1).optional().describe("Logical cluster identity used for leader election (defaults to service name).")
+}).describe("Service-registration annotations governing cluster behaviour."));
+var ClusterDriverSchema = zod.z.enum([
+  "memory",
+  // single-process; in-EventEmitter + Map + mutex + int
+  "redis",
+  // Redis Pub/Sub + SETNX-with-TTL + GET/SET + INCR
+  "postgres",
+  // LISTEN/NOTIFY + advisory locks + KV table + sequence
+  "nats",
+  // NATS subjects + KV bucket lock + KV bucket + KV INCR
+  "custom"
+  // Plugin-provided driver; runtime looks it up by name.
+]).describe("Cluster transport driver.");
+var ClusterTenantIsolationSchema = zod.z.enum(["channel-prefix", "none"]).describe("How tenant traffic is separated on shared transports.");
+var ClusterCapabilityConfigSchema = lazySchema(() => zod.z.object({
+  /**
+   * Transport driver. Defaults to `memory` (single-process). Production
+   * deployments must override this to a distributed driver.
+   * @default 'memory'
+   */
+  driver: ClusterDriverSchema.optional().default("memory").describe("Cluster transport driver. Defaults to in-memory single-process."),
+  /**
+   * Driver-specific connection string. Required for `redis` and `nats`,
+   * optional for `postgres` (defaults to the main DB pool when
+   * `useExistingPool` is true).
+   */
+  url: zod.z.string().url().optional().describe("Driver-specific connection URL."),
+  /**
+   * When `driver === 'postgres'`, reuse the main application database
+   * pool instead of opening a dedicated one. Recommended for small/medium
+   * deployments — zero new infrastructure.
+   * @default true
+   */
+  useExistingPool: zod.z.boolean().optional().default(true).describe("Reuse the main DB pool for the postgres driver."),
+  /**
+   * Stable identifier for this node. Used by leader election and trace
+   * correlation. Auto-generated (UUIDv4) if absent; setting it explicitly
+   * makes logs and lock owners human-readable.
+   */
+  nodeId: zod.z.string().min(1).optional().describe("Stable node identifier. Auto-generated when absent."),
+  /**
+   * Leader-election heartbeat interval in milliseconds. The lock TTL must
+   * be ≥ 3× this value; the runtime validates the ratio at startup.
+   * @default 5000
+   */
+  heartbeatMs: zod.z.number().int().min(100).optional().default(5e3).describe("Leader-election heartbeat interval in milliseconds."),
+  /**
+   * Lock time-to-live in milliseconds. Safe ratio is 3× `heartbeatMs`.
+   * Shorter TTLs recover faster from crashed leaders but risk flapping
+   * under transient network slowness.
+   * @default 15000
+   */
+  lockTtlMs: zod.z.number().int().min(100).optional().default(15e3).describe("Leader-election lock TTL in milliseconds (\u2265 3\xD7 heartbeatMs)."),
+  /**
+   * Tenant isolation strategy on shared transports.
+   * @default 'channel-prefix'
+   */
+  tenantIsolation: ClusterTenantIsolationSchema.optional().default("channel-prefix").describe("Channel/key namespacing strategy for multi-tenant deployments."),
+  /**
+   * Per-driver options passed verbatim to the driver implementation.
+   * The protocol does not validate these — drivers do.
+   */
+  driverOptions: zod.z.record(zod.z.string(), zod.z.unknown()).optional().describe("Driver-specific opaque options.")
+}).describe("Cluster capability configuration for the stack."));
+var MetadataChangeOperationSchema = zod.z.enum([
+  "create",
+  "update",
+  "delete",
+  "publish"
+]).describe("Persistence operation that triggered the change.");
+var MetadataChangedEventPayloadSchema = lazySchema(() => zod.z.object({
+  /**
+   * Metadata type — e.g. `'object'`, `'view'`, `'flow'`, `'agent'`.
+   * Matches the `MetadataTypeSchema` enum.
+   */
+  type: zod.z.string().min(1).describe('Metadata type (e.g. "object", "view").'),
+  /**
+   * Machine name of the changed item.
+   */
+  name: zod.z.string().min(1).describe("Machine name of the metadata item."),
+  /**
+   * Tenant scope when the change is tenant-overlaid. Absent for
+   * platform-default metadata.
+   */
+  tenantId: zod.z.string().optional().describe("Tenant id when the change is overlay-scoped."),
+  /**
+   * Monotonic version of the record after the change. Readers compare
+   * this with their cached value; only strictly greater versions
+   * invalidate.
+   *
+   * Modelled as `bigint` in the schema to support long-running clusters
+   * without 32-bit wraparound concerns; persisted as `numeric` / `int8`
+   * in storage.
+   */
+  version: zod.z.bigint().describe("Monotonic version of the record after the change."),
+  /**
+   * The operation that produced this version.
+   */
+  operation: MetadataChangeOperationSchema,
+  /**
+   * Optional correlation id for tracing the change back to a request /
+   * deploy / migration that produced it.
+   */
+  correlationId: zod.z.string().optional().describe("Trace correlation id of the originating request.")
+}).describe("Canonical payload for the metadata:changed cluster event."));
 var TenantIsolationLevel = zod.z.enum([
   "shared_schema",
   // Shared DB, shared schema, row-level isolation (most economical)
@@ -762,7 +919,19 @@ var EventMetadataSchema = lazySchema(() => zod.z.object({
   tenantId: zod.z.string().optional().describe("Tenant identifier for multi-tenant systems"),
   correlationId: zod.z.string().optional().describe("Correlation ID for event tracing"),
   causationId: zod.z.string().optional().describe("ID of the event that caused this event"),
-  priority: EventPriority.optional().default("normal").describe("Event priority")
+  priority: EventPriority.optional().default("normal").describe("Event priority"),
+  /**
+   * Cluster routing & ordering options.
+   *
+   * Optional for backward compatibility — events without this field
+   * default to `{ scope: 'local', deliverySemantics: 'best-effort' }`,
+   * which is identical to the pre-v5.2 behaviour. Plugins that need
+   * cross-node delivery, ordering, or persisted at-least-once semantics
+   * MUST set the relevant fields.
+   *
+   * @see content/docs/concepts/cluster-semantics.mdx §4
+   */
+  cluster: EventClusterOptionsSchema.optional().describe("Per-emit cluster routing & delivery options. See cluster-semantics.mdx \xA74.")
 }));
 var EventTypeDefinitionSchema = lazySchema(() => zod.z.object({
   name: EventNameSchema.describe("Event type name (lowercase with dots)"),
@@ -3189,7 +3358,7 @@ var MetadataTypeSchema = lazySchema(() => zod.z.enum([
   "skill"
   // AI skill definitions (SkillSchema)
 ]));
-var MetadataTypeRegistryEntrySchema = lazySchema(() => zod.z.object({
+var MetadataTypeRegistryEntryBaseSchema = zod.z.object({
   /** Metadata type identifier (e.g., 'object', 'view') */
   type: MetadataTypeSchema.describe("Metadata type identifier"),
   /** Human-readable label */
@@ -3231,6 +3400,29 @@ var MetadataTypeRegistryEntrySchema = lazySchema(() => zod.z.object({
    * When true, changes are tracked with version history.
    */
   supportsVersioning: zod.z.boolean().default(false).describe("Whether version history is tracked"),
+  /**
+   * Whether runtime transaction rows pin a specific historical version of
+   * this metadata by content hash (ADR-0009).
+   *
+   * Types with `executionPinned: true` give the strongest persistence
+   * guarantee in the system:
+   *
+   * 1. History rows for this type are **never** garbage-collected,
+   *    regardless of `MetadataHistoryRetentionPolicy`.
+   * 2. `MetadataRepository.getByHash(ref, hash)` MUST return the
+   *    pinned body for any hash that was ever HEAD.
+   * 3. Implies `supportsVersioning: true` (enforced via superRefine on
+   *    the wrapping `MetadataTypeRegistryEntrySchema`).
+   *
+   * Use this flag for metadata describing executable business processes
+   * whose runtime invocations can pause across redeploys
+   * (`flow`, `workflow`, `approval`). Do **not** set it for types whose
+   * runtime state captures outputs rather than the source body
+   * (`agent`, `tool`).
+   */
+  executionPinned: zod.z.boolean().default(false).describe(
+    "Transaction rows reference a specific version_hash; history GC is disabled and getByHash() MUST resolve old hashes (ADR-0009)"
+  ),
   /**
    * Priority order for loading (lower = earlier).
    * Objects load before views, views before dashboards.
@@ -3238,7 +3430,18 @@ var MetadataTypeRegistryEntrySchema = lazySchema(() => zod.z.object({
   loadOrder: zod.z.number().int().min(0).default(100).describe("Loading priority (lower = earlier)"),
   /** The domain this type belongs to */
   domain: zod.z.enum(["data", "ui", "automation", "system", "security", "ai"]).describe("Protocol domain")
-}));
+});
+var MetadataTypeRegistryEntrySchema = lazySchema(
+  () => MetadataTypeRegistryEntryBaseSchema.superRefine((entry, ctx) => {
+    if (entry.executionPinned && !entry.supportsVersioning) {
+      ctx.addIssue({
+        code: zod.z.ZodIssueCode.custom,
+        path: ["executionPinned"],
+        message: `executionPinned requires supportsVersioning: true (type '${entry.type}')`
+      });
+    }
+  })
+);
 var MetadataQuerySchema = lazySchema(() => zod.z.object({
   /** Filter by metadata type(s) */
   types: zod.z.array(MetadataTypeSchema).optional().describe("Filter by metadata types"),
@@ -3344,7 +3547,7 @@ var MetadataPluginConfigSchema = lazySchema(() => zod.z.object({
    * Additional metadata type registrations.
    * Used by plugins to register custom metadata types beyond the built-in set.
    */
-  additionalTypes: zod.z.array(MetadataTypeRegistryEntrySchema.omit({ type: true }).extend({
+  additionalTypes: zod.z.array(MetadataTypeRegistryEntryBaseSchema.omit({ type: true }).extend({
     type: zod.z.string().describe("Custom metadata type identifier")
   })).optional().describe("Additional custom metadata types"),
   /**
@@ -3432,37 +3635,37 @@ var MetadataPluginManifestSchema = lazySchema(() => zod.z.object({
 }));
 var DEFAULT_METADATA_TYPE_REGISTRY = [
   // Data Protocol (load first)
-  { type: "object", label: "Object", filePatterns: ["**/*.object.ts", "**/*.object.yml", "**/*.object.json"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: false, supportsVersioning: true, loadOrder: 10, domain: "data" },
-  { type: "field", label: "Field", filePatterns: ["**/*.field.ts", "**/*.field.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 20, domain: "data" },
-  { type: "trigger", label: "Trigger", filePatterns: ["**/*.trigger.ts", "**/*.trigger.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 30, domain: "data" },
-  { type: "validation", label: "Validation Rule", filePatterns: ["**/*.validation.ts", "**/*.validation.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 30, domain: "data" },
-  { type: "hook", label: "Hook", filePatterns: ["**/*.hook.ts", "**/*.hook.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 30, domain: "data" },
+  { type: "object", label: "Object", filePatterns: ["**/*.object.ts", "**/*.object.yml", "**/*.object.json"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: false, supportsVersioning: true, executionPinned: false, loadOrder: 10, domain: "data" },
+  { type: "field", label: "Field", filePatterns: ["**/*.field.ts", "**/*.field.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 20, domain: "data" },
+  { type: "trigger", label: "Trigger", filePatterns: ["**/*.trigger.ts", "**/*.trigger.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 30, domain: "data" },
+  { type: "validation", label: "Validation Rule", filePatterns: ["**/*.validation.ts", "**/*.validation.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 30, domain: "data" },
+  { type: "hook", label: "Hook", filePatterns: ["**/*.hook.ts", "**/*.hook.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 30, domain: "data" },
   // UI Protocol
-  { type: "view", label: "View", filePatterns: ["**/*.view.ts", "**/*.view.yml", "**/*.view.json"], supportsOverlay: true, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 50, domain: "ui" },
-  { type: "page", label: "Page", filePatterns: ["**/*.page.ts", "**/*.page.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 50, domain: "ui" },
-  { type: "dashboard", label: "Dashboard", filePatterns: ["**/*.dashboard.ts", "**/*.dashboard.yml", "**/*.dashboard.json"], supportsOverlay: true, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 60, domain: "ui" },
-  { type: "app", label: "Application", filePatterns: ["**/*.app.ts", "**/*.app.yml", "**/*.app.json"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: false, supportsVersioning: true, loadOrder: 70, domain: "ui" },
-  { type: "action", label: "Action", filePatterns: ["**/*.action.ts", "**/*.action.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 50, domain: "ui" },
-  { type: "report", label: "Report", filePatterns: ["**/*.report.ts", "**/*.report.yml"], supportsOverlay: true, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 60, domain: "ui" },
-  // Automation Protocol
-  { type: "flow", label: "Flow", filePatterns: ["**/*.flow.ts", "**/*.flow.yml", "**/*.flow.json"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: true, loadOrder: 80, domain: "automation" },
-  { type: "workflow", label: "Workflow", filePatterns: ["**/*.workflow.ts", "**/*.workflow.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: true, loadOrder: 80, domain: "automation" },
-  { type: "approval", label: "Approval Process", filePatterns: ["**/*.approval.ts", "**/*.approval.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 80, domain: "automation" },
+  { type: "view", label: "View", filePatterns: ["**/*.view.ts", "**/*.view.yml", "**/*.view.json"], supportsOverlay: true, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 50, domain: "ui" },
+  { type: "page", label: "Page", filePatterns: ["**/*.page.ts", "**/*.page.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 50, domain: "ui" },
+  { type: "dashboard", label: "Dashboard", filePatterns: ["**/*.dashboard.ts", "**/*.dashboard.yml", "**/*.dashboard.json"], supportsOverlay: true, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 60, domain: "ui" },
+  { type: "app", label: "Application", filePatterns: ["**/*.app.ts", "**/*.app.yml", "**/*.app.json"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: false, supportsVersioning: true, executionPinned: false, loadOrder: 70, domain: "ui" },
+  { type: "action", label: "Action", filePatterns: ["**/*.action.ts", "**/*.action.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 50, domain: "ui" },
+  { type: "report", label: "Report", filePatterns: ["**/*.report.ts", "**/*.report.yml"], supportsOverlay: true, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 60, domain: "ui" },
+  // Automation Protocol — flow/workflow/approval are executionPinned (ADR-0009)
+  { type: "flow", label: "Flow", filePatterns: ["**/*.flow.ts", "**/*.flow.yml", "**/*.flow.json"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: true, executionPinned: true, loadOrder: 80, domain: "automation" },
+  { type: "workflow", label: "Workflow", filePatterns: ["**/*.workflow.ts", "**/*.workflow.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: true, executionPinned: true, loadOrder: 80, domain: "automation" },
+  { type: "approval", label: "Approval Process", filePatterns: ["**/*.approval.ts", "**/*.approval.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: true, executionPinned: true, loadOrder: 80, domain: "automation" },
   // System Protocol
-  { type: "datasource", label: "Datasource", filePatterns: ["**/*.datasource.ts", "**/*.datasource.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: false, supportsVersioning: false, loadOrder: 5, domain: "system" },
-  { type: "translation", label: "Translation", filePatterns: ["**/*.translation.ts", "**/*.translation.yml", "**/*.translation.json"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 90, domain: "system" },
-  { type: "router", label: "Router", filePatterns: ["**/*.router.ts"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: false, supportsVersioning: false, loadOrder: 40, domain: "system" },
-  { type: "function", label: "Function", filePatterns: ["**/*.function.ts"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: false, supportsVersioning: false, loadOrder: 40, domain: "system" },
-  { type: "service", label: "Service", filePatterns: ["**/*.service.ts"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: false, supportsVersioning: false, loadOrder: 40, domain: "system" },
-  { type: "email_template", label: "Email Template", filePatterns: ["**/*.email-template.ts", "**/*.email-template.yml", "**/*.email-template.json"], supportsOverlay: true, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 85, domain: "system" },
+  { type: "datasource", label: "Datasource", filePatterns: ["**/*.datasource.ts", "**/*.datasource.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: false, supportsVersioning: false, executionPinned: false, loadOrder: 5, domain: "system" },
+  { type: "translation", label: "Translation", filePatterns: ["**/*.translation.ts", "**/*.translation.yml", "**/*.translation.json"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 90, domain: "system" },
+  { type: "router", label: "Router", filePatterns: ["**/*.router.ts"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: false, supportsVersioning: false, executionPinned: false, loadOrder: 40, domain: "system" },
+  { type: "function", label: "Function", filePatterns: ["**/*.function.ts"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: false, supportsVersioning: false, executionPinned: false, loadOrder: 40, domain: "system" },
+  { type: "service", label: "Service", filePatterns: ["**/*.service.ts"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: false, supportsVersioning: false, executionPinned: false, loadOrder: 40, domain: "system" },
+  { type: "email_template", label: "Email Template", filePatterns: ["**/*.email-template.ts", "**/*.email-template.yml", "**/*.email-template.json"], supportsOverlay: true, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 85, domain: "system" },
   // Security Protocol
-  { type: "permission", label: "Permission Set", filePatterns: ["**/*.permission.ts", "**/*.permission.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: true, loadOrder: 15, domain: "security" },
-  { type: "profile", label: "Profile", filePatterns: ["**/*.profile.ts", "**/*.profile.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 15, domain: "security" },
-  { type: "role", label: "Role", filePatterns: ["**/*.role.ts", "**/*.role.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 15, domain: "security" },
+  { type: "permission", label: "Permission Set", filePatterns: ["**/*.permission.ts", "**/*.permission.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: true, executionPinned: false, loadOrder: 15, domain: "security" },
+  { type: "profile", label: "Profile", filePatterns: ["**/*.profile.ts", "**/*.profile.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 15, domain: "security" },
+  { type: "role", label: "Role", filePatterns: ["**/*.role.ts", "**/*.role.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 15, domain: "security" },
   // AI Protocol
-  { type: "agent", label: "AI Agent", filePatterns: ["**/*.agent.ts", "**/*.agent.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: true, loadOrder: 90, domain: "ai" },
-  { type: "tool", label: "AI Tool", filePatterns: ["**/*.tool.ts", "**/*.tool.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 85, domain: "ai" },
-  { type: "skill", label: "AI Skill", filePatterns: ["**/*.skill.ts", "**/*.skill.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, loadOrder: 88, domain: "ai" }
+  { type: "agent", label: "AI Agent", filePatterns: ["**/*.agent.ts", "**/*.agent.yml"], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: true, executionPinned: false, loadOrder: 90, domain: "ai" },
+  { type: "tool", label: "AI Tool", filePatterns: ["**/*.tool.ts", "**/*.tool.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 85, domain: "ai" },
+  { type: "skill", label: "AI Skill", filePatterns: ["**/*.skill.ts", "**/*.skill.yml"], supportsOverlay: true, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 88, domain: "ai" }
 ];
 var MetadataBulkRegisterRequestSchema = lazySchema(() => zod.z.object({
   /** Items to register */
@@ -5747,7 +5950,15 @@ var ServiceMetadataSchema = lazySchema(() => zod.z.object({
   /**
    * Additional metadata
    */
-  metadata: zod.z.record(zod.z.string(), zod.z.unknown()).optional().describe("Additional service-specific metadata")
+  metadata: zod.z.record(zod.z.string(), zod.z.unknown()).optional().describe("Additional service-specific metadata"),
+  /**
+   * Cluster annotations governing how this service behaves in a
+   * multi-node deployment. Optional — omitting it is equivalent to
+   * `{ clusterScope: 'node' }`, which is correct on a single machine.
+   *
+   * @see content/docs/concepts/cluster-semantics.mdx §5
+   */
+  cluster: ServiceClusterAnnotationsSchema.optional().describe("Cluster scope & leader strategy. See cluster-semantics.mdx \xA75.")
 }));
 var ServiceRegistryConfigSchema = lazySchema(() => zod.z.object({
   /**
@@ -5791,7 +6002,11 @@ var ServiceFactoryRegistrationSchema = lazySchema(() => zod.z.object({
   /**
    * Whether this is a singleton (cache factory result)
    */
-  singleton: zod.z.boolean().optional().default(true).describe("Whether to cache the factory result (singleton pattern)")
+  singleton: zod.z.boolean().optional().default(true).describe("Whether to cache the factory result (singleton pattern)"),
+  /**
+   * Cluster annotations. See `ServiceMetadataSchema.cluster`.
+   */
+  cluster: ServiceClusterAnnotationsSchema.optional().describe("Cluster scope & leader strategy for this service.")
 }));
 var ScopeConfigSchema = lazySchema(() => zod.z.object({
   /**
@@ -6826,6 +7041,14 @@ var ExecutionContextSchema = lazySchema(() => zod.z.object({
   roles: zod.z.array(zod.z.string()).default([]),
   /** Aggregated permission names (resolved from PermissionSet) */
   permissions: zod.z.array(zod.z.string()).default([]),
+  /**
+   * IDs of all users in the active organization. Pre-resolved so RLS
+   * expressions can scope visibility of identity tables (`sys_user`)
+   * via `IN (current_user.org_user_ids)` without needing subquery
+   * support in the RLS compiler. Populated by the runtime's
+   * resolveExecutionContext from `sys_member`.
+   */
+  org_user_ids: zod.z.array(zod.z.string()).optional(),
   /** Whether this is a system-level operation (bypasses permission checks) */
   isSystem: zod.z.boolean().default(false),
   /** Raw access token (for external API call pass-through) */
@@ -6845,6 +7068,9 @@ exports.BreakingChangeSchema = BreakingChangeSchema;
 exports.CLICommandContributionSchema = CLICommandContributionSchema;
 exports.CORE_PLUGIN_TYPES = CORE_PLUGIN_TYPES;
 exports.CapabilityConformanceLevelSchema = CapabilityConformanceLevelSchema;
+exports.ClusterCapabilityConfigSchema = ClusterCapabilityConfigSchema;
+exports.ClusterDriverSchema = ClusterDriverSchema;
+exports.ClusterTenantIsolationSchema = ClusterTenantIsolationSchema;
 exports.CompatibilityLevelSchema = CompatibilityLevelSchema;
 exports.CompatibilityMatrixEntrySchema = CompatibilityMatrixEntrySchema;
 exports.CustomizationOriginSchema = CustomizationOriginSchema;
@@ -6874,6 +7100,8 @@ exports.EVENT_PRIORITY_VALUES = EVENT_PRIORITY_VALUES;
 exports.EnablePackageRequestSchema = EnablePackageRequestSchema;
 exports.EnablePackageResponseSchema = EnablePackageResponseSchema;
 exports.EventBusConfigSchema = EventBusConfigSchema;
+exports.EventClusterOptionsSchema = EventClusterOptionsSchema;
+exports.EventDeliverySemanticsSchema = EventDeliverySemanticsSchema;
 exports.EventHandlerSchema = EventHandlerSchema;
 exports.EventLogEntrySchema = EventLogEntrySchema;
 exports.EventMessageQueueConfigSchema = EventMessageQueueConfigSchema;
@@ -6885,6 +7113,7 @@ exports.EventQueueConfigSchema = EventQueueConfigSchema;
 exports.EventReplayConfigSchema = EventReplayConfigSchema;
 exports.EventRouteSchema = EventRouteSchema;
 exports.EventSchema = EventSchema;
+exports.EventScopeSchema = EventScopeSchema;
 exports.EventSourcingConfigSchema = EventSourcingConfigSchema;
 exports.EventTypeDefinitionSchema = EventTypeDefinitionSchema;
 exports.EventWebhookConfigSchema = EventWebhookConfigSchema;
@@ -6920,7 +7149,9 @@ exports.MergeStrategyConfigSchema = MergeStrategyConfigSchema;
 exports.MetadataBulkRegisterRequestSchema = MetadataBulkRegisterRequestSchema;
 exports.MetadataBulkResultSchema = MetadataBulkResultSchema;
 exports.MetadataCategoryEnum = MetadataCategoryEnum;
+exports.MetadataChangeOperationSchema = MetadataChangeOperationSchema;
 exports.MetadataChangeTypeSchema = MetadataChangeTypeSchema;
+exports.MetadataChangedEventPayloadSchema = MetadataChangedEventPayloadSchema;
 exports.MetadataCollectionInfoSchema = MetadataCollectionInfoSchema;
 exports.MetadataDependencySchema = MetadataDependencySchema;
 exports.MetadataDiffItemSchema = MetadataDiffItemSchema;
@@ -7031,7 +7262,10 @@ exports.SecurityPolicySchema = SecurityPolicySchema;
 exports.SecurityScanResultSchema = SecurityScanResultSchema;
 exports.SecurityVulnerabilitySchema = SecurityVulnerabilitySchema;
 exports.SemanticVersionSchema = SemanticVersionSchema;
+exports.ServiceClusterAnnotationsSchema = ServiceClusterAnnotationsSchema;
+exports.ServiceClusterScopeSchema = ServiceClusterScopeSchema;
 exports.ServiceFactoryRegistrationSchema = ServiceFactoryRegistrationSchema;
+exports.ServiceLeaderStrategySchema = ServiceLeaderStrategySchema;
 exports.ServiceMetadataSchema = ServiceMetadataSchema;
 exports.ServiceRegisteredEventSchema = ServiceRegisteredEventSchema;
 exports.ServiceRegistryConfigSchema = ServiceRegistryConfigSchema;