@elevasis/core 0.22.0 → 0.24.0

package/src/operations/activities/api-schemas.ts

@@ -1,80 +1,80 @@
-import { z } from 'zod'
-import { NonEmptyStringSchema } from '../../platform/utils/validation'
-
-/**
- * Activity Log API Validation Schemas
- *
- * Zod schemas for Activity Log endpoints with security controls:
- * - Mass assignment prevention (.strict() mode)
- * - Size limits (title: 200 chars, description: 1000 chars)
- * - Enum validation (activityType, status)
- * - Metadata size limits (50KB)
- */
-
-// Activity type enum
-export const ActivityTypeSchema = z.enum([
-  'workflow_execution',
-  'agent_run',
-  'hitl_action',
-  'webhook_received',
-  'webhook_executed',
-  'webhook_failed',
-  'credential_change',
-  'credential_read',
-  'api_key_change',
-  'deployment_change',
-  'membership_change'
-])
-
-// Activity status enum
-export const ActivityStatusSchema = z.enum(['success', 'failure', 'pending', 'approved', 'rejected', 'completed'])
-
-// Metadata schema with size limit (50KB)
-const MetadataSchema = z
-  .record(z.string(), z.unknown())
-  .refine((val) => JSON.stringify(val).length <= 50_000, 'Metadata exceeds 50KB limit')
-  .optional()
-
-// POST /api/activities - Create activity
-export const CreateActivitySchema = z
-  .object({
-    activityType: ActivityTypeSchema,
-    status: ActivityStatusSchema,
-    title: NonEmptyStringSchema.max(200),
-    description: z.string().max(1000).optional(),
-    entityType: NonEmptyStringSchema.max(100),
-    entityId: NonEmptyStringSchema.max(255),
-    entityName: z.string().max(255).optional(),
-    metadata: MetadataSchema,
-    occurredAt: z.string().datetime().optional(),
-    actorId: z.string().uuid().optional(),
-    actorType: z.enum(['user', 'system', 'api_key']).optional()
-    // NO organizationId (always from JWT/API key context)
-  })
-  .strict()
-
-// GET /api/activities/trend - Activity trend timestamps query params
-export const ActivityTrendQuerySchema = z
-  .object({
-    activityType: ActivityTypeSchema.optional(),
-    entityType: z.string().max(100).optional(),
-    entityId: z.string().max(255).optional(),
-    startDate: z.string().datetime().optional(),
-    endDate: z.string().datetime().optional()
-  })
-  .strict()
-
-// GET /api/activities - List activities query params
-export const ListActivitiesQuerySchema = z
-  .object({
-    limit: z.coerce.number().int().min(1).max(100).default(50),
-    offset: z.coerce.number().int().min(0).default(0),
-    activityType: ActivityTypeSchema.optional(),
-    entityType: z.string().max(100).optional(),
-    entityId: z.string().max(255).optional(),
-    startDate: z.string().datetime().optional(),
-    endDate: z.string().datetime().optional(),
-    status: ActivityStatusSchema.optional(),
-    search: z.string().max(200).optional()
-  })
-  .strict()
+import { z } from 'zod'
+import { NonEmptyStringSchema } from '../../platform/utils/validation'
+
+/**
+ * Activity Log API Validation Schemas
+ *
+ * Zod schemas for Activity Log endpoints with security controls:
+ * - Mass assignment prevention (.strict() mode)
+ * - Size limits (title: 200 chars, description: 1000 chars)
+ * - Enum validation (activityType, status)
+ * - Metadata size limits (50KB)
+ */
+
+// Activity type enum
+export const ActivityTypeSchema = z.enum([
+  'workflow_execution',
+  'agent_run',
+  'hitl_action',
+  'webhook_received',
+  'webhook_executed',
+  'webhook_failed',
+  'credential_change',
+  'credential_read',
+  'api_key_change',
+  'deployment_change',
+  'membership_change'
+])
+
+// Activity status enum
+export const ActivityStatusSchema = z.enum(['success', 'failure', 'pending', 'approved', 'rejected', 'completed'])
+
+// Metadata schema with size limit (50KB)
+const MetadataSchema = z
+  .record(z.string(), z.unknown())
+  .refine((val) => JSON.stringify(val).length <= 50_000, 'Metadata exceeds 50KB limit')
+  .optional()
+
+// POST /api/activities - Create activity
+export const CreateActivitySchema = z
+  .object({
+    activityType: ActivityTypeSchema,
+    status: ActivityStatusSchema,
+    title: NonEmptyStringSchema.max(200),
+    description: z.string().max(1000).optional(),
+    entityType: NonEmptyStringSchema.max(100),
+    entityId: NonEmptyStringSchema.max(255),
+    entityName: z.string().max(255).optional(),
+    metadata: MetadataSchema,
+    occurredAt: z.string().datetime().optional(),
+    actorId: z.string().uuid().optional(),
+    actorType: z.enum(['user', 'system', 'api_key']).optional()
+    // NO organizationId (always from JWT/API key context)
+  })
+  .strict()
+
+// GET /api/activities/trend - Activity trend timestamps query params
+export const ActivityTrendQuerySchema = z
+  .object({
+    activityType: ActivityTypeSchema.optional(),
+    entityType: z.string().max(100).optional(),
+    entityId: z.string().max(255).optional(),
+    startDate: z.string().datetime().optional(),
+    endDate: z.string().datetime().optional()
+  })
+  .strict()
+
+// GET /api/activities - List activities query params
+export const ListActivitiesQuerySchema = z
+  .object({
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+    offset: z.coerce.number().int().min(0).default(0),
+    activityType: ActivityTypeSchema.optional(),
+    entityType: z.string().max(100).optional(),
+    entityId: z.string().max(255).optional(),
+    startDate: z.string().datetime().optional(),
+    endDate: z.string().datetime().optional(),
+    status: ActivityStatusSchema.optional(),
+    search: z.string().max(200).optional()
+  })
+  .strict()

package/src/operations/activities/types.ts

@@ -1,64 +1,64 @@
-import type { Database } from '../../supabase/database.types'
-
-export type ActivityRow = Database['public']['Tables']['activities']['Row']
-export type ActivityInsert = Database['public']['Tables']['activities']['Insert']
-
-export type ActivityType =
-  | 'workflow_execution'
-  | 'agent_run'
-  | 'hitl_action'
-  | 'webhook_received'
-  | 'webhook_executed'
-  | 'webhook_failed'
-  | 'credential_change'
-  | 'credential_read'
-  | 'api_key_change'
-  | 'deployment_change'
-  | 'membership_change'
-
-export type ActivityStatus = 'success' | 'failure' | 'pending' | 'approved' | 'rejected' | 'completed'
-
-export interface Activity {
-  id: string
-  organizationId: string
-  activityType: ActivityType
-  status: ActivityStatus
-  title: string
-  description: string | null
-  entityType: string
-  entityId: string
-  entityName: string | null
-  metadata: Record<string, unknown> | null
-  actorId: string | null
-  actorType: string | null
-  occurredAt: Date
-  createdAt: Date
-}
-
-export interface CreateActivityParams {
-  organizationId: string
-  activityType: ActivityType
-  status: ActivityStatus
-  title: string
-  description?: string
-  entityType: string
-  entityId: string
-  entityName?: string
-  metadata?: Record<string, unknown>
-  actorId?: string
-  actorType?: string
-  occurredAt?: Date
-}
-
-export interface ListActivitiesParams {
-  organizationId: string
-  limit?: number
-  offset?: number
-  activityType?: ActivityType
-  entityType?: string
-  entityId?: string
-  startDate?: string
-  endDate?: string
-  status?: string
-  search?: string
-}
+import type { Database } from '../../supabase/database.types'
+
+export type ActivityRow = Database['public']['Tables']['activities']['Row']
+export type ActivityInsert = Database['public']['Tables']['activities']['Insert']
+
+export type ActivityType =
+  | 'workflow_execution'
+  | 'agent_run'
+  | 'hitl_action'
+  | 'webhook_received'
+  | 'webhook_executed'
+  | 'webhook_failed'
+  | 'credential_change'
+  | 'credential_read'
+  | 'api_key_change'
+  | 'deployment_change'
+  | 'membership_change'
+
+export type ActivityStatus = 'success' | 'failure' | 'pending' | 'approved' | 'rejected' | 'completed'
+
+export interface Activity {
+  id: string
+  organizationId: string
+  activityType: ActivityType
+  status: ActivityStatus
+  title: string
+  description: string | null
+  entityType: string
+  entityId: string
+  entityName: string | null
+  metadata: Record<string, unknown> | null
+  actorId: string | null
+  actorType: string | null
+  occurredAt: Date
+  createdAt: Date
+}
+
+export interface CreateActivityParams {
+  organizationId: string
+  activityType: ActivityType
+  status: ActivityStatus
+  title: string
+  description?: string
+  entityType: string
+  entityId: string
+  entityName?: string
+  metadata?: Record<string, unknown>
+  actorId?: string
+  actorType?: string
+  occurredAt?: Date
+}
+
+export interface ListActivitiesParams {
+  organizationId: string
+  limit?: number
+  offset?: number
+  activityType?: ActivityType
+  entityType?: string
+  entityId?: string
+  startDate?: string
+  endDate?: string
+  status?: string
+  search?: string
+}

package/src/organization-model/README.md

@@ -1,109 +1,149 @@
-# Organization Model
-
-The organization model is the published semantic contract that maps a tenant's product shape to flat feature hierarchy, shell navigation, business semantics, and graph bindings.
-
-Use this module when resolving or validating an organization's contract before wiring UI shells, routing, feature gates, or domain-specific capability checks.
-
-## Published Exports
-
-The public entry point exposes:
-
-- `OrganizationModelSchema`
-- `FeatureSchema`
-- `DEFAULT_ORGANIZATION_MODEL`
-- `defineOrganizationModel`
-- `resolveOrganizationModel`
-- `createFoundationOrganizationModel`
-- node ID and feature helper types
-- `OrganizationModel` and supporting domain types
-
-Import it from the published subpath:
-
-```ts
-import {
-  DEFAULT_ORGANIZATION_MODEL,
-  createFoundationOrganizationModel,
-  defineOrganizationModel,
-  resolveOrganizationModel,
-  type OrganizationModel
-} from '@elevasis/core/organization-model'
-```
-
-## Contract Shape
-
-The model is versioned and currently validates against `version: 1`.
-
-Top-level fields:
-
-- `version`
-- `branding`
-- `features`
-- `navigation`
-- `sales`
-- `prospecting`
-- `projects`
-- `identity`
-- `customers`
-- `offerings`
-- `roles`
-- `goals`
-- `systems`
-- `resources`
-- `statuses`
-- `operations`
-- `knowledge`
-
-Resource identity is authored in `resources.entries`. Runtime workflows, agents, and integrations import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
-
-## Feature Set
-
-Feature hierarchy is authored as a flat array. Dotted IDs define parent/child relationships:
-
-```ts
-features: [
-  { id: 'dashboard', label: 'Dashboard', enabled: true, path: '/', uiPosition: 'sidebar-primary' },
-  { id: 'sales', label: 'Sales', enabled: true, uiPosition: 'sidebar-primary' },
-  { id: 'sales.crm', label: 'CRM', enabled: true, path: '/crm' },
-  { id: 'operations.resources', label: 'Resources', enabled: true, path: '/operations/resources' }
-]
-```
-
-Containers omit `path`; leaves provide `path`. `uiPosition`, `requiresAdmin`, and `devOnly` inherit from ancestors.
-Development-only features remain in the contract with `enabled: true` and `devOnly: true`; shell consumers hide them and guard their paths outside development mode.
-
-## Graph IDs
-
-Cross-collection links use kind-prefixed IDs:
-
-- `feature:sales.crm`
-- `integration:instantly`
-- `resource:lead-import`
-- `capability:operations.queue.review`
-
-## Resource Descriptors
-
-The OM Resources domain is governance-only. Descriptors declare canonical `id`, required `systemId`, governance `status`, and optional role ownership. `DeploymentSpec` remains the runtime/deploy assembly around those descriptors, not a second resource identity catalog.
-
-## Resolution Semantics
-
-- `defineOrganizationModel()` is a typed helper.
-- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates it.
-- `createFoundationOrganizationModel()` resolves the canonical model and returns UI-facing helper outputs.
-- Plain objects merge recursively.
-- Arrays replace the default value.
-- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
-
-## Referential Integrity
-
-- Feature IDs must be unique.
-- Child feature IDs require ancestor feature nodes.
-- Container features omit `path`.
-- Leaf features provide `path`.
-- Systems, resources, roles, knowledge nodes, and goals must resolve their declared cross-references.
-
-## Practical Guidance
-
-- Use `resolveOrganizationModel()` when you need a runtime-safe model.
-- Use `defineOrganizationModel()` when authoring static overrides.
-- Keep feature IDs stable because shell routing, gating, breadcrumbs, and docs depend on them.
-- Put resource identity and governance in `resources.entries`; attach executable behavior in operations.
+# Organization Model
+
+The organization model is the published semantic contract that maps a tenant's System hierarchy, shell navigation, business semantics, resource governance, and graph bindings.
+
+Use this module when resolving or validating an organization's contract before wiring UI shells, routing, system gates, or domain-specific capability checks.
+
+## Published Exports
+
+The public entry point exposes:
+
+- `OrganizationModelSchema`
+- `DEFAULT_ORGANIZATION_MODEL`
+- `defineOrganizationModel`
+- `resolveOrganizationModel`
+- `createFoundationOrganizationModel`
+- node ID and System helper types
+- `OrganizationModel` and supporting domain types
+
+Import it from the published subpath:
+
+```ts
+import {
+  DEFAULT_ORGANIZATION_MODEL,
+  createFoundationOrganizationModel,
+  defineOrganizationModel,
+  resolveOrganizationModel,
+  type OrganizationModel
+} from '@elevasis/core/organization-model'
+```
+
+## Contract Shape
+
+The model is versioned and currently validates against `version: 1`.
+
+Top-level fields:
+
+- `version`
+- `domainMetadata`
+- `branding`
+- `navigation`
+- `sales`
+- `prospecting`
+- `projects`
+- `identity`
+- `customers`
+- `offerings`
+- `roles`
+- `goals`
+- `systems`
+- `resources`
+- `capabilities`
+- `policies`
+- `statuses`
+- `knowledge`
+
+The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `customers`, `offerings`, `resources`, `capabilities`, `policies`, and `statuses`. The map key must match the entry `id`. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters.
+
+Resource identity is authored in `resources`. Runtime workflows, agents, integrations, and scripts import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
+
+## System Set
+
+System hierarchy is authored as an id-keyed `systems` map. Dotted IDs and `parentSystemId` define parent/child relationships:
+
+```ts
+systems: {
+  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
+  sales: { id: 'sales', order: 20, label: 'Sales', lifecycle: 'active' },
+  clients: { id: 'clients', order: 30, label: 'Clients', lifecycle: 'active' },
+  projects: { id: 'projects', order: 40, label: 'Projects', lifecycle: 'active' }
+}
+```
+
+Systems describe semantic ownership, hierarchy, lifecycle, access, and governance. Sidebar presentation is authored separately under `navigation.sidebar`; UI-backed Systems may still provide `ui.path` for route matching during the migration, but they do not author composed surface lists. Lifecycle values such as `active`, `beta`, `deprecated`, and `archived` replace the old feature enabled/dev-only split.
+
+## Sidebar Navigation
+
+Shell navigation is authored as a recursive sidebar tree:
+
+```ts
+navigation: {
+  sidebar: {
+    primary: {
+      dashboard: {
+        type: 'surface',
+        order: 10,
+        label: 'Dashboard',
+        path: '/',
+        surfaceType: 'dashboard',
+        targets: { systems: ['dashboard'] }
+      },
+      business: {
+        type: 'group',
+        order: 20,
+        label: 'Business',
+        children: {
+          clients: {
+            type: 'surface',
+            order: 20,
+            label: 'Clients',
+            path: '/clients',
+            surfaceType: 'list',
+            targets: { systems: ['clients'] }
+          }
+        }
+      }
+    },
+    bottom: {}
+  }
+}
+```
+
+Routeable sidebar leaves are projected into flat semantic surface DTOs by `projectOrganizationSurfaces(model)`. Do not author top-level `surfaces` or `navigationGroups` fields on `OrganizationModel`.
+
+## Graph IDs
+
+Cross-collection links use kind-prefixed IDs:
+
+- `system:sales.crm`
+- `integration:instantly`
+- `resource:lead-import`
+- `action:operations.queue.review`
+
+## Resource Descriptors
+
+The OM Resources domain is governance-only. Descriptors declare canonical `id`, required `systemPath`, governance `status`, and optional role ownership. `DeploymentSpec` remains the runtime/deploy assembly around those descriptors, not a second resource identity catalog.
+
+## Resolution Semantics
+
+- `defineOrganizationModel()` is a typed helper.
+- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates it.
+- `createFoundationOrganizationModel()` resolves the canonical model and returns UI-facing helper outputs.
+- Plain objects merge recursively.
+- Id-keyed domain maps merge additively by key.
+- Arrays replace the default value.
+- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
+
+## Referential Integrity
+
+- System IDs must be unique.
+- Child System IDs require valid ancestors or `parentSystemId` links.
+- Systems with UI provide `ui.path`.
+- Systems, resources, roles, knowledge nodes, and goals must resolve their declared cross-references.
+
+## Practical Guidance
+
+- Use `resolveOrganizationModel()` when you need a runtime-safe model.
+- Use `defineOrganizationModel()` when authoring static overrides.
+- Keep System IDs stable because shell routing, gating, breadcrumbs, and docs depend on them.
+- Put resource identity and governance in `resources`; attach executable behavior in operations.