Shared domain contracts and utilities
The twenty-shared package defines the common language used by the server, web client, SDK, workflows, AI features, and installable applications. It keeps records, metadata, permissions, messages, events, rich text, localization, and safety rules consistent when data crosses package or process boundaries. See shared platform for the wider package map and UI component system for the client surface.
Domain model
Record and field types
The shared domain model gives records one shape and one set of rules across queries, layouts, permissions, exports, and user actions. ObjectRecord is the base record shape, while FieldMetadataType names scalar, relation, composite, file, and search field kinds. Composite fields group values such as names, addresses, currencies, links, email addresses, phones, actors, and rich text under one field contract.
The field vocabulary also defines default values, selectable options, actor sources, and rich-text formats. An inactive select option stays valid on existing records but is no longer available for new choices. The model keeps the old blocknote value readable while clients move to tiptap and markdown. Relation, polymorphic relation, file, and search-vector fields do not accept ordinary defaults.
References: packages/…/index.ts• L36-69 packages/…/FieldMetadataType.ts• L1-27 packages/…/FieldMetadataOptions.ts• L5-37 packages/…/actor.composite-type.ts• L8-71 packages/…/composite-type.interface.ts• L4-20 packages/…/rich-text.composite-type.ts• L6-37 packages/…/FieldMetadataDefaultValue.ts• L69-128
Query, access, and navigation types
Query contracts describe selected fields, variables, filters, sorting, aggregation, and grouping. The same filter language covers scalar, relation, composite, array, file, JSON, rich-text, and full-text values, so views, workflows, permissions, and local matchers can ask the same questions.
Access contracts separate all-record permissions from row-level permissions. ObjectRecordsPermissions states which operations can reach every record and which fields are hidden or locked. RowLevelRecordsPermissions adds predicates for restricted records. Shared reach checks answer whether an operation can reach all records or at least some records. Filter helpers also define which workspace-member fields can safely participate in row-level rules.
Navigation types give the client one vocabulary for application routes, settings routes, command-menu context, and menu item kinds such as views, folders, links, native pages, tabs, sections, workflows, and agents. Feature flags use the same boundary to name staged capabilities such as AI chat, record sharing, access groups, private records, lookup columns, and related-record paths.
References: packages/…/RecordGqlOperationFilter.ts• L1-40 packages/…/ObjectRecordsPermissions.ts• L3-12 packages/…/RowLevelRecordsPermissions.ts• L4-15 packages/…/canReachSomeRecords.ts• L7-36 packages/…/getFieldOrSubFieldType.ts• L1-43 packages/…/getRlsPredicateCompatibleWorkspaceMemberFieldTypes.ts• L1-31 packages/…/FeatureFlagKey.ts• L1-25 packages/…/NavigationMenuItemType.ts• L1-14 packages/…/AppPath.ts• L1-44 packages/…/SettingsPath.ts• L1-119
Application contracts
Manifest resources
Application manifests describe portable application resources. They join identity with objects, fields, indexes, permissions, roles, agents, connections, logic, UI, layouts, navigation, workflows, messages, translations, validation rules, timeline activity types, source files, and billing. Universal identifiers let the host recognize the same resource during install, update, export, and sync.
The manifest model keeps product meaning separate from workspace-local IDs. Views carry portable field references plus filters, groups, and sorts. Applications can add views without taking ownership of engine-provided default views. Front components can appear on record pages or dashboards. Command-menu items can point to a front component and define when they are available or pinned. Navigation items can target views, records, page layouts, agents, workflows, native pages, links, or nested sections. Older folder references are normalized to the current parent reference.
Source-file manifests describe restorable application source with checksums. They exclude package and lock files from the restorable source list. Application export coverage lets the host report which portable resources and files it can reproduce. Permission resources use deterministic universal identifiers, including system side-effect role targets, so the same logical resource stays stable across workspaces.
References: packages/…/manifestType.ts• L37-70 packages/…/frontComponentManifestType.ts• L10-46 packages/…/navigationMenuItemManifestType.ts• L5-20 packages/…/normalizeNavigationMenuItemManifest.ts• L4-25 packages/…/isRestorableApplicationSourcePath.ts• L1-16 packages/…/isSourceFileManifestList.ts• L6-28 packages/…/get-system-side-effect-role-target-universal-identifier.util.ts• L3-16 packages/…/TwentyPublicAppUniversalIdentifiers.ts• L1-12 packages/…/application-export.type.ts• L7-39 packages/…/application-manifest-sync-result.type.ts• L3-7
Application permissions
Application roles express access at workspace, object, field, and row levels. The current shape groups record permissions by object and keeps nested row predicates inside a rule, while legacy role fields remain readable during migration.
Shared utilities identify which legacy permission keys are actually present, normalize old and new role shapes, flatten nested rules for storage or comparison, and rebuild the nested form for manifests. They also compare effective grants and row restrictions, so a role can be checked against a broader role without treating a different row predicate as equivalent access.
References: packages/…/roleManifestType.ts• L63-152 packages/…/getDeclaredLegacyRoleRecordsPermissionsKeys.ts• L4-20 packages/…/normalizeLegacyCompliantRoleManifest.ts• L105-324 packages/…/flattenRowLevelPermissionRuleManifests.ts• L20-87 packages/…/nestRowLevelPermissionRuleManifests.ts• L26-141 packages/…/getRoleManifestGrantsNotCoveredBy.ts• L87-227 packages/…/getReachableObjectPermissionsFromRoleManifest.ts• L8-38
Agents, messaging, and inbox actions
Agent manifests define a named assistant with a prompt, model choices, response format, optional role, and triggers. Messaging provider manifests connect an external account to a message channel and can describe either chat or email conversation style. App connections give both the app runtime and server one wire shape for provider identity, account identity, scope, granted scopes, and re-authentication state.
The application message contract keeps chat and email payloads distinct. Both use an idempotency key, external thread identity, recipients, and bounded attachments. Email adds subject, HTML, copy recipients, and reply linkage. Inbox actions carry the provider account and external thread needed to mark a thread as read or to archive it for selected workspace members. Application settings use a shared connections section identity so app connection screens remain addressable across clients.
References: packages/…/agentManifestType.ts• L8-22 packages/…/appConnectionType.ts• L8-48 packages/…/messagingProviderConversationStyleType.ts• L1-7 packages/…/messagingProviderManifestType.ts• L4-11 packages/…/sendAppMessageType.ts• L3-46 packages/…/markAppThreadAsReadType.ts• L1-6 packages/…/MaxAppMessageAttachmentsPerMessage.ts• L1 packages/…/SettingsApplicationConnectionsSectionId.ts• L1
Marketplace and connection identities
Marketplace contracts give a built-in application a stable identity and the public information needed to show it in an app catalog. First-party public apps use shared universal identifiers so server, client, and marketplace data refer to the same app. Verified OAuth clients link an approved client to a marketplace application and use either a known registration identity or a discovery document URL.
Connection providers support OAuth, OAuth discovery, custom credentials, and API keys. The provider contract joins the user-facing provider name with account identification and connect or disconnect actions, so an application can use one connection model across provider types.
References: packages/…/TwentyPublicAppUniversalIdentifiers.ts• L1-12 packages/…/marketplace-built-in-application.type.ts• L1-12 packages/…/verified-oauth-client.type.ts• L1-7 packages/…/connectionProviderManifestType.ts• L7-26 packages/…/connectionProviderType.ts• L1-5 packages/…/MarketplaceAppMcpServerUrlPlaceholder.ts• L1
Application runtime
Application runtime contracts resolve how an application reaches the platform. Requests made only to Twenty may use an internal API URL when one is configured. URLs exposed to browsers or third parties continue to use the public API URL.
The runtime entry point also exposes the shared names for API keys, app tokens, functions, server routes, connection scopes, and credit availability. These names keep application code aligned with the host without copying environment or credential rules locally.
References: packages/…/DefaultInternalApiUrlName.ts• L1 packages/…/resolveApiUrlFromEnvironment.ts• L6-15 packages/…/index.ts• L10-24
Front-component build boundary
The front-component build contract lets an installable component type-check against approved shared dependencies. It checks both the component and a small preview entry point, reports clear TypeScript diagnostics, and records the source files used by the build.
The boundary limits type-reference data and names the required React and UI dependencies. A build manifest records checksums for the build, package files, lock file, and type references. CSS and its allowed media assets become browser-safe injected output, so a component can carry its styles without exposing a second asset contract.
References: packages/…/collect-front-component-type-references.ts• L5-18 packages/…/encode-front-component-type-references-or-throw.ts• L5-16 packages/…/get-front-component-type-diagnostics.ts• L6-117 packages/…/css-injection-plugin.ts• L20-79 packages/…/front-component-required-shared-dependencies.ts• L1-7 packages/…/shared-dependencies-build-manifest.type.ts• L3-9
Metadata contracts
Stable identities and resource names
Metadata contracts give configurable objects, fields, views, layouts, permissions, agents, workflows, connections, and other resources stable names and identities. ALL_METADATA_NAME defines the resource kinds that use the shared metadata boundary. Reserved names keep application resources from colliding with platform resources or query words.
Standard objects include their fields, indexes, views, relation targets, and record-page layout identities. AI chat threads, participants, targets, turns, messages, and message parts use the same durable metadata model as CRM, workflow, calendar, and message records. The identity snapshot records the expected standard set, so an identity change is treated as a compatibility change rather than a label change.
References: packages/…/all-metadata-name.constant.ts• L1-45 packages/…/reserved-metadata-name-keywords.constant.ts• L1-70 packages/…/standard-object-fields.constant.ts• L10-104 packages/…/standard-object.constant.ts• L6-18 packages/…/standard-page-layout-universal-identifiers.constant.ts• L1-20 packages/…/standardObjectUniversalIdentifiers.test.ts.snap• L1-15
Metadata views and permissions
Metadata views turn a portable object definition into a usable record surface. A view can define visible fields, filters, filter groups, groups, field groups, sorts, and layout choices. The same field universal identifiers connect those choices to the object and its fields. Manifest views are additional views; engine-owned default views remain outside application ownership.
Permission predicates use field and relation references to describe which rows a role can create, read, update, soft-delete, or destroy. The access result keeps field restrictions beside row rules, so callers can distinguish “the row is reachable” from “every field is readable or editable.”
References: packages/…/viewManifestType.ts• L21-103 packages/…/RowLevelPermissionPredicate.ts• L6-18 packages/…/RowLevelRecordsPermissions.ts• L4-15 packages/…/isRowLevelRecordsPermissionsRuleGrantingOperation.ts• L5-33
Metadata synchronization
Metadata synchronization describes portable changes as create, update, and delete actions. Updates may include a before-and-after diff, while deletes may identify the resource that caused a cascade. This gives application install, export, and workspace migration flows one change language.
References: packages/…/SyncAction.ts• L1-32 packages/…/application-manifest-sync-result.type.ts• L3-7
Workspace contracts
Workspace readiness and enrichment
Workspace contracts describe whether a workspace is ready for normal use and how enrichment reports its result. They let callers distinguish a provisioned workspace or a matched record from a pending, unavailable, or transient result.
The shared readiness check uses the activation status. Person and company enrichment use a result shape that separates a match with data from an unavailable result without data.
References: packages/…/WorkspaceActivationStatus.ts• L1-8 packages/…/isWorkspaceProvisioned.ts• L5-15 packages/…/WorkspaceEnrichmentResult.ts• L1-9
Workflow contracts
Workflow definitions and actions
Workflow contracts describe automation as a typed graph with triggers, actions, outputs, pauses, runs, and validation. The editor, application manifest, validator, and runtime use the same shapes so a saved definition remains meaningful when it moves between those surfaces.
Triggers cover manual starts, schedules, database events, and webhooks. Actions cover record work, communication, calendar work, code, logic functions, AI, classification, data selection, branching, iteration, delays, forms, filters, HTTP requests, and event waits. The action type selects the settings shape for that action.
Record filters and sorts use portable metadata field references. Email actions use the shared serialized email document. Calendar actions carry time, time zone, attendee, invitation, and conferencing data. Code actions use a bounded inline source or a legacy logic-function reference. MCP tool actions can derive an initial input from a JSON schema so required tool fields have a predictable starting shape.
References: packages/…/index.ts• L38-140 packages/…/workflow-action-schema.ts• L1-48 packages/…/find-records-action-settings-schema.ts• L8-29 packages/…/send-email-action-settings-schema.ts• L7-39 packages/…/create-calendar-event-action-settings-schema.ts• L4-19 packages/…/getDefaultMcpToolInputFromJsonSchema.ts• L5-53
Workflow waits and conversations
Conversation scopes control how an AI step reuses context. RUN shares one conversation across a run, STEP creates one for each step execution, and KEY shares a conversation across runs that use the same key.
Wait contracts pause a step until a callback, time, matching record event, or conversation answer occurs. Event waits can narrow the match by event, record, and changed fields. A timeout has an explicit outcome, so a paused run always has a defined next state.
This diagram shows how an external response or event returns a paused workflow to normal execution.
flowchart LR
A[Workflow step] --> B[Pending wait]
B --> C{Callback time event or answer}
C --> D[Resume step]
C --> E[Timeout outcome]
D --> F[Next workflow step]
References: packages/…/workflow-conversation-schema.ts• L3-10 packages/…/workflow-step-wait-schema.ts• L3-9 packages/…/pending-wake-up-condition-schema.ts• L3-18
Workflow AI steps
AI workflow steps have two modes. An agent step uses an existing agent's instructions, model, and permissions. A generation step defines its own prompt, response format, model configuration, and optional object or field scope.
The shared contract prevents the two modes from being mixed. It also blocks repeated object or field entries in a scope because each resource must have one clear permission. Only active non-system agents can run as workflow steps, and automation cannot write to workflow runtime, chat, member, dashboard, or connected-account sync records.
References: packages/…/ai-agent-action-settings-schema.ts• L8-20 packages/…/ai-agent-inline-config-schema.ts• L6-13 packages/…/getWorkflowAiAgentStepConfigIssues.ts• L11-31 packages/…/has-ai-run-scope-repeated-entries.util.ts• L4-21 packages/…/ObjectsBlockedFromAutomation.ts• L3-16
Workflow outputs and validation
Output schemas describe the values produced by records, searches, forms, code, manual triggers, and iterators. Variable lookup uses those schemas, so the editor and runtime resolve the same paths.
Workflow validation separates malformed definitions from drafts that are valid to edit but cannot be activated. It checks the graph, execution paths, step settings, variable paths, AI settings, conversations, cycles, and iterator returns. A workflow run keeps a compatible state with status, state, step logs, timing, and workflow identity. Run schemas accept the stored shape needed to read past runs, including older step settings that no longer match the active action shape.
Iterator bodies must return to their enclosing iterator. Ordinary cycles and missing returns are errors because they can leave a run stuck after one item. Validation reports issue severity and code so a draft warning is not confused with an activation-blocking error.
References: packages/…/OutputSchema.ts• L9-109 packages/…/validate-workflow-structure.util.ts• L14-76 packages/…/validate-workflow-execution-paths.util.ts• L10-73 packages/…/validate-workflow-step-params.util.ts• L31-99 packages/…/non-activable-workflow-validation-issue-codes.constant.ts• L3-24 packages/…/workflow-run-schema.ts• L6-19 packages/…/workflow-run-state-schema.ts• L35-49
Timeline contracts
Activity history
Timeline contracts turn record activity into a small history language for views and renderers. A timeline action is created, updated, deleted, restored, linked, or unlinked, regardless of the source event name.
An activity snapshot preserves the identity, label, action, icon, target object, and optional front component as they were at event time. Renderer identifiers let consumers recognize built-in message and calendar renderers without rebuilding the source event model.
References: packages/…/TimelineActivityAction.ts• L3-18 packages/…/parseTimelineActivityAction.ts• L6-12 packages/…/TimelineActivityTypeSnapshot.ts• L1-12 packages/…/StandardTimelineActivityRendererUniversalIdentifier.ts• L1-14
AI contracts
Chat messages and references
AI contracts connect agent runs, chat messages, inbox state, tools, reactions, workflows, assistant profiles, and data policy. They give clients one message and stream language while the server preserves permissions, usage, model data, and review state.
AgentMessageRow is the stored message shape. ExtendedUIMessage is the client shape. The shared projection orders message parts, carries sender and turn metadata, maps supported text, files, sources, and tool parts, and drops tool parts without a call ID because those parts cannot be replayed.
Chat references are bounded tokens that can point to assistants or records. Record-reference extraction accepts only references for the requested object and UUID-shaped record IDs. Markdown reference extraction keeps references that appear in rendered text while ignoring escaped references, links, images, and other non-text Markdown positions.
References: packages/…/AgentMessageRow.ts• L3-16 packages/…/ExtendedUIMessage.ts• L5-34 packages/…/map-agent-messages-to-ui-messages.util.ts• L6-33 packages/…/extract-record-reference-ids.util.ts• L4-28 packages/…/get-markdown-text-chat-references.util.ts• L5-13 packages/…/get-markdown-text-chat-references.util.ts• L106-128
Dictation event listeners
The dictation listener contract gives AI chat input one callback shape for speech events. A DictationEngineListener receives interim or final text, recording state changes, and typed failure reasons so the chat surface can update live input and explain engine problems through one event boundary.
The event vocabulary separates text that may still change from text ready for insertion. It also distinguishes the idle and recording states from failures such as denied permission, missing hardware, an unsupported surface, a silent engine, a network issue, or another engine error.
References: packages/…/DictationEngineListener.ts• L1-3 packages/…/DictationEngineEvent.ts• L1-8 packages/…/DictationEngineState.ts• L1 packages/…/DictationFailureReason.ts• L1-8
Inbox state and tool names
Inbox state contracts share read, archive, snooze, follow, unsubscribe, assignment, and mention behavior between optimistic client updates and server writes. Mention state compares the last mention time with the resolution time, so a newer mention remains visible.
Tool-name constants give stored and current AI tools one vocabulary. Tool names also follow a shared lower snake-case rule. The singular record-attachment name remains readable for old messages, while the plural name represents the current operation that attaches one conversation to multiple records.
References: packages/…/AgentChatInboxState.ts• L1-8 packages/…/apply-agent-chat-inbox-action.util.ts• L8-86 packages/…/is-snake-case-tool-name.util.ts• L1-4 packages/…/attach-conversation-to-record-tool-name.const.ts• L1-3 packages/…/attach-conversation-to-records-tool-name.const.ts• L1-2 packages/…/index.ts• L136-176
Assistant profiles and data policy
The assistant profile contract keeps an assistant's visible identity consistent across settings, chat, and references. It limits the display name and shares the allowed avatar shape, color, face, and animation values.
AI data policy contracts express workspace limits for residency, retention, and product-improvement data sharing. Model compliance checks compare the model's residency and retention behavior with the workspace policy. Content recording is allowed only when the policy is inactive and sharing is enabled.
References: packages/…/get-ai-chat-assistant-profile-schema.ts• L9-21 packages/…/is-valid-chat-reference-label.util.ts• L1-11 packages/…/AiDataPolicy.ts• L1-7 packages/…/data-residencies-by-region.const.ts• L1-9 packages/…/is-ai-content-recording-allowed.util.ts• L4-8 packages/…/is-ai-model-compliant-with-data-policy.util.ts• L8-40
Tool proposals and run summaries
Tool proposals let an agent describe an action for a person to review before execution. The proposal carries its tool, arguments, display data, alternatives, current values, and state. States distinguish review, execution, rejection, failure, conflict, and skip.
Agent run summaries give model choice, token use, credit cost, web search, tool calls, and duration one shared result shape. Workflow AI logs reuse that summary so an agent surface and a workflow surface report the same usage and outcome. Tool execution context carries workspace, actor, user, agent, thread, workflow, authorization, and outbound-request identity into the operation, while tool output can return a result, warning, record references, or a file for model input.
References: packages/…/ProposedToolCall.ts• L1-15 packages/…/proposed-tool-call-templates.const.ts• L1-8 packages/…/tool-category.const.ts• L1-15 packages/…/agent-run-summary-schema.ts• L3-30 packages/…/workflow-run-step-log-schema.ts• L11-15 packages/…/tool-execution-context.type.ts• L7-20 packages/…/tool-output.type.ts• L4-15 packages/…/code-interpreter-input.type.ts• L1-12
Event contracts
Record-change events
Database event contracts carry record changes between the data layer, workflows, integrations, and other consumers. They identify the record and workspace and can include the before state, after state, changed fields, and structured differences.
Create, update, delete, destroy, restore, and upsert events share a base shape. A database event adds the event name, workspace ID, and object metadata snapshot so consumers can identify both the change and its object type.
References: packages/…/object-record.base.event.ts• L3-16 packages/…/object-record-update.event.ts• L4-13 packages/…/database-event-payload.type.ts• L3-48
Localization contracts
Locale and message lookup
Localization contracts keep message lookup, metadata labels, and text direction consistent across locales. The locale set includes source and regional locales plus a pseudo locale that helps expose layout and translation problems.
The i18n factory caches one message instance per locale and falls back to source-locale messages when needed. Locale normalization accepts case-insensitive and language-only values while rejecting unsupported values. Metadata placeholders keep object labels, plural labels, icons, and record-aware labels in a closed vocabulary.
Text direction is part of the shared locale result. Arabic and Hebrew return rtl; other supported locales return ltr. Text marked doNotTranslate stays unchanged during localization checks.
References: packages/…/create-i18n-instance-factory.ts• L6-27 packages/…/AppLocales.ts• L3-40 packages/…/metadata-label-placeholder.ts• L4-27 packages/…/getLocaleTextDirection.ts• L3-19 packages/…/do-not-translate.ts• L1-2
Utility contracts
Rich text and Markdown documents
Rich text uses a versioned document model for paragraphs, headings, lists, tasks, toggles, tables, code, images, files, mentions, links, colors, and alignment. The schema checks node shape, URL safety, heading and indent bounds, marks, and schema version before content is stored or rendered.
Email bodies accept a shared input contract for a rich-text document, HTML, or plain text. New email input is converted to a versioned email document. Empty content has a stable empty document shape. Workflow email actions require serialized email documents when they contain a body. Older stored bodies are upgraded by the server's version command rather than by the shared package.
Converters move older BlockNote content into the shared rich-text form and project valid TipTap blocks to Markdown. The Markdown projection preserves links, mentions, skill tags, nested lists, task state, tables, and code while applying safe escaping.
References: packages/…/rich-text-document-schema.ts• L16-58 packages/…/email-document-schema.ts• L8-28 packages/…/email-body-input-schema.ts• L5-11 packages/…/convert-email-body-input-to-email-document.ts• L7-39 packages/…/empty-email-document.ts• L1-9 packages/…/tiptap-document-to-markdown.ts• L159-273 packages/…/convert-blocknote-to-rich-text-document.ts• L526-543 packages/…/convert-email-body-to-email-document.util.ts• L13-39 packages/…/convert-string-body-to-email-document.util.ts• L29-70 packages/…/get-markdown-text-chat-references.util.ts• L106-128
Data, query, and safety utilities
Shared utilities preserve the meaning of dates, time zones, currency micros, serialized relations, arrays, and nested objects at package boundaries. They also centralize CSV safety, URL checks, iframe media rules, file-size display, permissions, navigation, page layouts, and record exports.
Query utilities convert metadata-aware filters into GraphQL filters and provide local matchers for the same values. They handle relation and polymorphic relation paths, composite subfields, relative dates, empty values, arrays, files, JSON, and links. Operand maps and value schemas keep editor validation, local matching, REST parsing, and server query conversion aligned.
Safety utilities keep ordinary links, iframe origins, internal paths, and image URLs under separate rules. Iframe permissions are the intersection of requested and allowed permissions. Date parsing returns one UTC instant or an explicit error, and CSV formatting sanitizes values before output.
The cache utilities provide bounded memoization for shared computations. Reads refresh recency and writes evict the oldest entries, so callers can reuse parsed or derived values without allowing an unbounded cache to grow.
References: packages/…/index.ts• L26-29 packages/…/index.ts• L48-67 packages/…/index.ts• L79-93 packages/…/index.ts• L115-240 packages/…/evictLeastRecentlyUsed.ts• L5-76 packages/…/memoizeLeastRecentlyUsed.ts• L5-26 packages/…/turnRecordFilterIntoGqlOperationFilter.ts• L149-226 packages/…/get-open-quote-after-character.ts• L1-31 packages/…/split-filter-array-items.ts• L1-34 packages/…/computeGqlOperationFilterForEmails.ts• L13-160 packages/…/getIframeMediaAllow.ts• L8-35 packages/…/parseToInstantOrThrow.ts• L31-56
Expression dates
Expression dates give validation rules one date value that can represent either a date-only value or a date-time value. Shared date parts and units define the allowed vocabulary for adding, comparing, truncating, and reading dates.
The date helpers parse valid values, convert them to UTC for comparison, and return a formatted value or an explicit null result when the input is not valid or falls outside the supported range. Calendar months and elapsed time use distinct rules, so a month is not treated as a fixed number of hours.
References: packages/…/ExpressionDate.ts• L1-5 packages/…/ExpressionDatePart.ts• L1-3 packages/…/ExpressionDateUnit.ts• L1-3 packages/…/ExpressionDateParts.ts• L1-10 packages/…/ExpressionDateUnits.ts• L1-4 packages/…/parseExpressionDate.ts• L7-24 packages/…/addToExpressionDate.ts• L44-71 packages/…/computeExpressionDateDifference.ts• L11-56 packages/…/getExpressionDatePart.ts• L7-40 packages/…/truncateExpressionDate.ts• L9-30
Validation rule expressions
Validation rule utilities let a record rule return a Boolean result from field values. The rule language can use supported functions, the current time through now, and previous values through previous when a prior record exists.
Path resolution binds field names to stable universal identifiers. It permits known composite subfields and one-to-one relation hops, but rejects unknown fields, deep paths, relation values in previous, unsafe syntax, and non-Boolean results. Evaluation reports passed, failed, or errored, so a rule mismatch stays distinct from a bad rule. Date functions use the shared expression-date contract and report invalid units or parts with specific error codes.
The expression parser is cached with a bounded least-recently-used cache. This avoids repeated parsing without making rule evaluation depend on an unbounded process-wide store.
References: packages/…/ValidationRuleExpressionSyntaxDescription.ts• L1-8 packages/…/ValidationRuleFunctions.ts• L11-55 packages/…/McpServerNameMaxLength.ts• L1 packages/…/resolveValidationRuleIdentifierPath.ts• L125-244 packages/…/buildValidationRuleEvaluationContext.ts• L82-180 packages/…/validationRuleParser.ts• L11-151 packages/…/parseValidationRuleExpression.ts• L1-9 packages/…/createValidationRuleEvaluator.ts• L20-81 packages/…/ValidationRuleErrorCode.ts• L1-19 packages/…/ValidationRuleEvaluationResult.ts• L1-10
Public contract surfaces
The shared package exposes explicit entry points for applications, application runtime, AI, front-component builds, Markdown, metadata, timelines, types, translations, utilities, workflows, workspaces, and pending wake-up conditions. Consumers should use these public contracts instead of creating local route, filter, event, tool, or state shapes.
This diagram shows how a producer and several consumers rely on one shared domain boundary.
flowchart LR
P[Server or SDK producer] --> C[twenty-shared public contract]
C --> F[Web client]
C --> A[Application runtime]
C --> W[Workflow and AI consumers]
C --> B[Front-component build]
Generated entry points make the public surface explicit. Browser dependency helpers include browser-safe shared subpaths and exclude node-only build entries. Documentation route constants come from the documentation navigation source and must be regenerated when that source changes.
References: packages/…/package.json• L65-145 packages/…/index.ts• L10-24 packages/…/index.ts• L58-176 packages/…/index.ts• L48-102 packages/…/index.ts• L10 packages/…/index.ts• L10-36 packages/…/index.ts• L1-449 packages/…/getTwentySharedOptimizeDepsInclude.ts• L1-11 packages/…/DocumentationPaths.ts• L1-20
Change checklist
When these files or sections are changed, remember to consider these:
- A standard object, field, view, index, or page-layout identity change must stay aligned with server provisioning, migrations, sync data, relations, permissions, and the identity snapshot.
- A new metadata kind must stay aligned across its name, flat entity, universal entity, maps, migration actions, and public entry point.
- A row-level permission change must preserve nested and legacy manifest normalization, declared legacy-key detection, flattening, deterministic identifiers, and the operation checks for object, field, and row access.
- An application manifest change must keep local IDs, universal identifiers, source-file checksums, restorable path rules, resource references, export coverage, install-time validation, and sync results aligned.
- A navigation change must preserve parent references, published-app compatibility, menu item types, settings paths, and client route handling.
- A messaging or connection change must keep provider type, scope, connected account, external thread identity, idempotency, attachment limits, OAuth identity, and email-only fields aligned.
- An application runtime URL change must keep internal platform requests separate from URLs exposed to browsers or third parties.
- A front-component build change must keep required shared dependencies, type-reference encoding, size limits, preview diagnostics, CSS asset rules, checksums, and browser-safe entry points aligned.
- An AI message, tool, reference, or dictation event change must stay aligned across stored rows or engine producers, message-part mapping, stream events, chat input consumers, Markdown parsing, record extraction, tool labels, tool-name format, execution context, metadata, and client rendering.
- An inbox action change must preserve read cursors, archive and snooze state, assignment, subscription, and mention resolution behavior.
- A workflow action, trigger, AI mode, loop, output, email document, MCP input, or run-state change must stay aligned across schemas, application manifests, validation, compatibility parsing, and runtime logs.
- A rich-text, email-document, Markdown-reference, filter, URL, iframe, date, currency, or CSV change must preserve its schema, safety limits, conversion rules, parser behavior, migration boundary, and public imports.
- A validation-rule change must keep reserved names,
now,previous, date parts, date units, path binding, supported relation depth, error codes, Boolean evaluation results, and parser cache behavior aligned. - A documentation path or shared entry-point change must update the source navigation or export map and regenerate derived public files.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A standard identity changes without its related metadata | Sync or migration can create duplicates or fail to match a resource | Stable identity constants and the snapshot expose unexpected changes |
| A row-level permission ID omits its application, role, object, or predicate-group input | Permissions can collide or attach to the wrong resource | Deterministic identifiers include the owning application and rule inputs |
| A legacy role is read as a new role without normalization | Object, field, and row grants can disappear or become broader than intended | Legacy role normalization and declared-key detection map old properties into recordsPermissions |
| A navigation item keeps only its old folder reference | A published app can lose its parent menu location | Navigation normalization maps the old folder reference to parentUniversalIdentifier |
| A source manifest includes a hidden path, duplicate path, package file, or bad checksum | Application restore or validation can accept unsafe input or fail to reproduce source | Restorable path and source-list guards reject invalid entries |
| A front component uses a missing or oversized type-reference bundle | The host cannot type-check or safely build the component | Required dependency rules and the encoding limit reject the bundle |
| A component CSS import has no build output or an unsupported asset path | The component loses its style or its build fails | The CSS boundary checks output and limits media loaders to approved extensions |
| A runtime request uses the internal URL for browser or third-party traffic | A private platform address can leak or fail outside the host network | URL resolution reserves the internal URL for requests to Twenty only |
| A stored AI message loses part order, a tool call ID, or sender metadata | The client can render a different message or cannot replay a tool call | The shared row-to-UI projection sorts parts and drops unreplayable tools |
| A dictation event is handled as the wrong kind or a failure reason is not surfaced | Interim speech can be committed as final text or the chat can hide why recording stopped | The listener uses a discriminated event type with explicit text, state, and failure variants |
| A tool name violates the shared format or a tool label is removed without a compatibility label | Tool registration can fail or older stored messages lose their readable action name | Snake-case validation and compatibility constants define the accepted names |
| A tool runs without the correct workspace or actor context | The tool can read or write under the wrong identity | Tool execution context carries workspace, authorization, actor, and run identity |
| A Markdown reference is found inside a link, image, or escaped text | A non-visible token can become a chat or record target | Markdown parsing keeps only unescaped references in rendered text |
| A workflow email body is saved as HTML or plain text | The step can fail validation or render with the wrong escaping rules | Email input conversion and step validation require a serialized email document |
| A workflow loop has no return edge or contains an ordinary cycle | A run can hang or never reach its next step | Execution-path validation reports iterator-return and cycle errors |
| A workflow variable points to an unknown or downstream output path | A later step receives no valid value | Validation requires a known upstream step and a resolved output path |
| A past workflow run is parsed only with the current step shape | Historical run state can become unreadable after a schema change | Run-state parsing keeps compatibility forms for past steps |
| A validation rule reads an unknown, deep, or non-to-one path | The rule can bind to the wrong value or fail at runtime | Path resolution returns a specific error code before evaluation |
| A date expression uses an unsupported unit or part | A rule can produce a false result or an unclear error | Shared date vocabularies and validation error codes reject invalid values |
| A filter value map changes without local matching or GraphQL conversion | A filter can pass one surface and change meaning in another | Shared operand maps, value schemas, matchers, parser helpers, and conversion use one contract |
| A rich-text or email document uses an unsafe URL, node, mark, or version | Content can be rejected, unsafe, or rendered differently | Shared schemas and URL checks bound stored document content |
| An unsupported locale or wrong text direction reaches the client | Messages can be missing or controls can render in the wrong direction | Locale fallback and direction helpers define the shared result |
Key files
| File | Why to read it |
|---|---|
| packages/…/package.json | Shows the public package boundary and entry points. |
| packages/…/index.ts | Shows the shared record and domain type surface. |
| packages/…/ObjectRecordsPermissions.ts | Shows all-record and row-level access results. |
| packages/…/manifestType.ts | Shows how applications join data, logic, UI, layout, connections, translations, and validation. |
| packages/…/frontComponentManifestType.ts | Shows the portable front-component and command-menu boundary. |
| packages/…/navigationMenuItemManifestType.ts | Shows the application navigation targets and parent relationship. |
| packages/…/roleManifestType.ts | Shows current and legacy application role permission shapes. |
| packages/…/normalizeLegacyCompliantRoleManifest.ts | Shows how older role contracts become the current permission model. |
| packages/…/viewManifestType.ts | Shows the portable view, field, filter, group, and sort boundary. |
| packages/…/appConnectionType.ts | Shows the application connection wire contract. |
| packages/…/resolveApiUrlFromEnvironment.ts | Shows the internal versus public API URL rule. |
| packages/…/get-front-component-type-diagnostics.ts | Shows the component and preview type-check boundary. |
| packages/…/css-injection-plugin.ts | Shows how component CSS and approved assets enter the browser build. |
| packages/…/standard-object.constant.ts | Shows how standard objects join fields, indexes, and views. |
| packages/…/SyncAction.ts | Defines portable metadata create, update, and delete changes. |
| packages/…/index.ts | Provides workflow schemas, validation, output contracts, and AI rules. |
| packages/…/validate-workflow-structure.util.ts | Shows the top-level workflow validation flow. |
| packages/…/send-email-action-settings-schema.ts | Shows the serialized email body boundary for workflow actions. |
| packages/…/ExtendedUIMessage.ts | Shows the client-facing AI message and usage metadata. |
| packages/…/map-agent-messages-to-ui-messages.util.ts | Shows the stored-message to client-message boundary. |
| packages/…/DictationEngineListener.ts | Defines the callback boundary for AI chat dictation events. |
| packages/…/DictationEngineEvent.ts | Defines interim, final, state, and error dictation events. |
| packages/…/database-event-payload.type.ts | Defines record-change events shared across system boundaries. |
| packages/…/rich-text-document-schema.ts | Defines the safe stored rich-text document boundary. |
| packages/…/memoizeLeastRecentlyUsed.ts | Shows the bounded cache contract used by shared computations. |
| packages/…/turnRecordFilterIntoGqlOperationFilter.ts | Defines metadata-aware filter conversion. |
| packages/…/resolveValidationRuleIdentifierPath.ts | Defines the allowed field and relation paths for validation rules. |
| packages/…/AppLocales.ts | Defines supported application locales. |
| packages/…/DocumentationPaths.ts | Defines generated documentation route names. |