@constructive-sdk/cli 0.20.7 → 0.20.8

package/esm/public/cli/commands.js

@@ -202,7 +202,8 @@ import copyTemplateToBlueprintCmd from './commands/copy-template-to-blueprint';
 import provisionSpatialRelationCmd from './commands/provision-spatial-relation';
 import bootstrapUserCmd from './commands/bootstrap-user';
 import setFieldOrderCmd from './commands/set-field-order';
-import appendSmartTagsCmd from './commands/append-smart-tags';
+import appendFieldSmartTagsCmd from './commands/append-field-smart-tags';
+import appendTableSmartTagsCmd from './commands/append-table-smart-tags';
 import provisionUniqueConstraintCmd from './commands/provision-unique-constraint';
 import provisionFullTextSearchCmd from './commands/provision-full-text-search';
 import provisionIndexCmd from './commands/provision-index';
@@ -424,7 +425,8 @@ const createCommandMap = () => ({
     'provision-spatial-relation': provisionSpatialRelationCmd,
     'bootstrap-user': bootstrapUserCmd,
     'set-field-order': setFieldOrderCmd,
-    'append-smart-tags': appendSmartTagsCmd,
+    'append-field-smart-tags': appendFieldSmartTagsCmd,
+    'append-table-smart-tags': appendTableSmartTagsCmd,
     'provision-unique-constraint': provisionUniqueConstraintCmd,
     'provision-full-text-search': provisionFullTextSearchCmd,
     'provision-index': provisionIndexCmd,
@@ -448,7 +450,7 @@ const createCommandMap = () => ({
     'provision-table': provisionTableCmd,
     'provision-bucket': provisionBucketCmd,
 });
-const usage = "\ncsdk <command>\n\nCommands:\n  context               Manage API contexts\n  auth                  Manage authentication\n  org-get-managers-record orgGetManagersRecord CRUD operations\n  org-get-subordinates-record orgGetSubordinatesRecord CRUD operations\n  get-all-record       getAllRecord CRUD operations\n  app-permission       appPermission CRUD operations\n  org-permission       orgPermission CRUD operations\n  object               object CRUD operations\n  app-level-requirement appLevelRequirement CRUD operations\n  database             database CRUD operations\n  schema               schema CRUD operations\n  table                table CRUD operations\n  check-constraint     checkConstraint CRUD operations\n  field                field CRUD operations\n  spatial-relation     spatialRelation CRUD operations\n  partition            partition CRUD operations\n  foreign-key-constraint foreignKeyConstraint CRUD operations\n  full-text-search     fullTextSearch CRUD operations\n  index                index CRUD operations\n  policy               policy CRUD operations\n  primary-key-constraint primaryKeyConstraint CRUD operations\n  table-grant          tableGrant CRUD operations\n  trigger              trigger CRUD operations\n  unique-constraint    uniqueConstraint CRUD operations\n  view                 view CRUD operations\n  view-table           viewTable CRUD operations\n  view-grant           viewGrant CRUD operations\n  view-rule            viewRule CRUD operations\n  embedding-chunk      embeddingChunk CRUD operations\n  secure-table-provision secureTableProvision CRUD operations\n  relation-provision   relationProvision CRUD operations\n  session-secrets-module sessionSecretsModule CRUD operations\n  identity-providers-module identityProvidersModule CRUD operations\n  realtime-module      realtimeModule CRUD operations\n  schema-grant         schemaGrant CRUD operations\n  default-privilege    defaultPrivilege CRUD operations\n  enum                 enum CRUD operations\n  function             function CRUD operations\n  api-schema           apiSchema CRUD operations\n  api-module           apiModule CRUD operations\n  domain               domain CRUD operations\n  site-metadatum       siteMetadatum CRUD operations\n  site-module          siteModule CRUD operations\n  site-theme           siteTheme CRUD operations\n  cors-setting         corsSetting CRUD operations\n  trigger-function     triggerFunction CRUD operations\n  database-transfer    databaseTransfer CRUD operations\n  api                  api CRUD operations\n  site                 site CRUD operations\n  app                  app CRUD operations\n  api-setting          apiSetting CRUD operations\n  connected-accounts-module connectedAccountsModule CRUD operations\n  crypto-addresses-module cryptoAddressesModule CRUD operations\n  crypto-auth-module   cryptoAuthModule CRUD operations\n  default-ids-module   defaultIdsModule CRUD operations\n  denormalized-table-field denormalizedTableField CRUD operations\n  emails-module        emailsModule CRUD operations\n  encrypted-secrets-module encryptedSecretsModule CRUD operations\n  invites-module       invitesModule CRUD operations\n  levels-module        levelsModule CRUD operations\n  limits-module        limitsModule CRUD operations\n  membership-types-module membershipTypesModule CRUD operations\n  memberships-module   membershipsModule CRUD operations\n  permissions-module   permissionsModule CRUD operations\n  phone-numbers-module phoneNumbersModule CRUD operations\n  profiles-module      profilesModule CRUD operations\n  secrets-module       secretsModule CRUD operations\n  sessions-module      sessionsModule CRUD operations\n  user-auth-module     userAuthModule CRUD operations\n  users-module         usersModule CRUD operations\n  blueprint            blueprint CRUD operations\n  blueprint-template   blueprintTemplate CRUD operations\n  blueprint-construction blueprintConstruction CRUD operations\n  storage-module       storageModule CRUD operations\n  entity-type-provision entityTypeProvision CRUD operations\n  webauthn-credentials-module webauthnCredentialsModule CRUD operations\n  webauthn-auth-module webauthnAuthModule CRUD operations\n  notifications-module notificationsModule CRUD operations\n  database-provision-module databaseProvisionModule CRUD operations\n  app-admin-grant      appAdminGrant CRUD operations\n  app-owner-grant      appOwnerGrant CRUD operations\n  app-grant            appGrant CRUD operations\n  org-membership       orgMembership CRUD operations\n  org-member           orgMember CRUD operations\n  org-admin-grant      orgAdminGrant CRUD operations\n  org-owner-grant      orgOwnerGrant CRUD operations\n  org-member-profile   orgMemberProfile CRUD operations\n  org-grant            orgGrant CRUD operations\n  org-chart-edge       orgChartEdge CRUD operations\n  org-chart-edge-grant orgChartEdgeGrant CRUD operations\n  org-permission-default orgPermissionDefault CRUD operations\n  app-limit            appLimit CRUD operations\n  app-limit-credit     appLimitCredit CRUD operations\n  app-limit-credit-code-item appLimitCreditCodeItem CRUD operations\n  app-limit-credit-redemption appLimitCreditRedemption CRUD operations\n  org-limit            orgLimit CRUD operations\n  org-limit-credit     orgLimitCredit CRUD operations\n  org-limit-aggregate  orgLimitAggregate CRUD operations\n  app-step             appStep CRUD operations\n  app-achievement      appAchievement CRUD operations\n  app-level            appLevel CRUD operations\n  email                email CRUD operations\n  phone-number         phoneNumber CRUD operations\n  crypto-address       cryptoAddress CRUD operations\n  webauthn-credential  webauthnCredential CRUD operations\n  app-invite           appInvite CRUD operations\n  app-claimed-invite   appClaimedInvite CRUD operations\n  org-invite           orgInvite CRUD operations\n  org-claimed-invite   orgClaimedInvite CRUD operations\n  audit-log            auditLog CRUD operations\n  agent-thread         agentThread CRUD operations\n  agent-message        agentMessage CRUD operations\n  agent-task           agentTask CRUD operations\n  role-type            roleType CRUD operations\n  identity-provider    identityProvider CRUD operations\n  ref                  ref CRUD operations\n  store                store CRUD operations\n  app-permission-default appPermissionDefault CRUD operations\n  app-limit-credit-code appLimitCreditCode CRUD operations\n  app-limit-caps-default appLimitCapsDefault CRUD operations\n  org-limit-caps-default orgLimitCapsDefault CRUD operations\n  app-limit-cap        appLimitCap CRUD operations\n  org-limit-cap        orgLimitCap CRUD operations\n  membership-type      membershipType CRUD operations\n  migrate-file         migrateFile CRUD operations\n  devices-module       devicesModule CRUD operations\n  node-type-registry   nodeTypeRegistry CRUD operations\n  app-limit-default    appLimitDefault CRUD operations\n  org-limit-default    orgLimitDefault CRUD operations\n  user-connected-account userConnectedAccount CRUD operations\n  commit               commit CRUD operations\n  pubkey-setting       pubkeySetting CRUD operations\n  rate-limits-module   rateLimitsModule CRUD operations\n  app-membership-default appMembershipDefault CRUD operations\n  org-membership-default orgMembershipDefault CRUD operations\n  rls-setting          rlsSetting CRUD operations\n  app-limit-event      appLimitEvent CRUD operations\n  org-limit-event      orgLimitEvent CRUD operations\n  rls-module           rlsModule CRUD operations\n  database-setting     databaseSetting CRUD operations\n  plans-module         plansModule CRUD operations\n  sql-action           sqlAction CRUD operations\n  billing-module       billingModule CRUD operations\n  ast-migration        astMigration CRUD operations\n  user                 user CRUD operations\n  org-membership-setting orgMembershipSetting CRUD operations\n  webauthn-setting     webauthnSetting CRUD operations\n  app-membership       appMembership CRUD operations\n  billing-provider-module billingProviderModule CRUD operations\n  hierarchy-module     hierarchyModule CRUD operations\n  current-user-id      currentUserId\n  current-user-agent   currentUserAgent\n  current-ip-address   currentIpAddress\n  require-step-up      requireStepUp\n  app-permissions-get-padded-mask appPermissionsGetPaddedMask\n  org-permissions-get-padded-mask orgPermissionsGetPaddedMask\n  steps-achieved       stepsAchieved\n  rev-parse            revParse\n  resolve-blueprint-field Resolves a field_name within a given table_id to a field_id. Throws if no match is found. Used by construct_blueprint to translate user-authored field names (e.g. \"location\") into field UUIDs for downstream provisioning procedures. table_id must already be resolved (via resolve_blueprint_table) before calling this.\n  org-is-manager-of    orgIsManagerOf\n  app-permissions-get-mask appPermissionsGetMask\n  org-permissions-get-mask orgPermissionsGetMask\n  resolve-blueprint-table Resolves a table_name (with optional schema_name) to a table_id. Resolution order: (1) if schema_name provided, exact lookup via metaschema_public.schema.name + metaschema_public.table; (2) check local table_map (tables created in current blueprint); (3) search metaschema_public.table by name across all schemas; (4) if multiple matches, throw ambiguous error asking for schema_name; (5) if no match, throw not-found error.\n  app-permissions-get-mask-by-names appPermissionsGetMaskByNames\n  org-permissions-get-mask-by-names orgPermissionsGetMaskByNames\n  app-permissions-get-by-mask Reads and enables pagination through a set of `AppPermission`.\n  org-permissions-get-by-mask Reads and enables pagination through a set of `OrgPermission`.\n  get-all-objects-from-root Reads and enables pagination through a set of `Object`.\n  get-path-objects-from-root Reads and enables pagination through a set of `Object`.\n  get-object-at-path   getObjectAtPath\n  steps-required       Reads and enables pagination through a set of `AppLevelRequirement`.\n  current-user         currentUser\n  send-account-deletion-email sendAccountDeletionEmail\n  sign-out             signOut\n  accept-database-transfer acceptDatabaseTransfer\n  cancel-database-transfer cancelDatabaseTransfer\n  reject-database-transfer rejectDatabaseTransfer\n  disconnect-account   disconnectAccount\n  revoke-api-key       revokeApiKey\n  revoke-session       revokeSession\n  verify-password      verifyPassword\n  verify-totp          verifyTotp\n  submit-app-invite-code submitAppInviteCode\n  submit-org-invite-code submitOrgInviteCode\n  check-password       checkPassword\n  confirm-delete-account confirmDeleteAccount\n  set-password         setPassword\n  verify-email         verifyEmail\n  freeze-objects       freezeObjects\n  init-empty-repo      initEmptyRepo\n  construct-blueprint  Executes a blueprint definition by delegating to provision_* procedures. Creates a blueprint_construction record to track the attempt. Six phases: (0) entity_type_provision for each membership_type entry \u2014 provisions entity tables, membership modules, and security, (1) provision_table() for each table with nodes[], fields[], policies[], and grants (table-level indexes/fts/unique_constraints are deferred), (2) provision_relation() for each relation, (3) provision_index() for top-level + deferred indexes, (4) provision_full_text_search() for top-level + deferred FTS, (5) provision_unique_constraint() for top-level + deferred unique constraints. Phase 0 entity tables are added to the table_map so subsequent phases can reference them by name. Table-level indexes/fts/unique_constraints are deferred to phases 3-5 so they can reference columns created by relations in phase 2. Returns the construction record ID on success, NULL on failure.\n  provision-new-user   provisionNewUser\n  reset-password       resetPassword\n  remove-node-at-path  removeNodeAtPath\n  copy-template-to-blueprint Creates a new blueprint by copying a template definition. Checks visibility: owners can always copy their own templates, others require public visibility. Increments the template copy_count. Returns the new blueprint ID.\n  provision-spatial-relation Idempotent provisioner for metaschema_public.spatial_relation. Inserts a row declaring a spatial predicate between two geometry/geography columns (owner and target). Called from construct_blueprint when a relation entry has $type=RelationSpatial. Graceful: re-running with the same (source_table_id, name) returns the existing id without modifying the row. Operator whitelist and st_dwithin \u2194 param_name pairing are enforced by the spatial_relation table CHECKs. Both fields must already exist \u2014 this is a metadata-only insert.\n  bootstrap-user       bootstrapUser\n  set-field-order      setFieldOrder\n  append-smart-tags    appendSmartTags\n  provision-unique-constraint Creates a unique constraint on a table. Accepts a jsonb definition with columns (array of field names). Graceful: skips if the exact same unique constraint already exists.\n  provision-full-text-search Creates a full-text search configuration on a table. Accepts a jsonb definition with field (tsvector column name) and sources (array of {field, weight, lang}). Graceful: skips if FTS config already exists for the same (table_id, field_id). Returns the fts_id.\n  provision-index      Creates an index on a table. Accepts a jsonb definition with columns (array of names or single column string), access_method (default BTREE), is_unique, op_classes, options, and name (auto-generated if omitted). Graceful: skips if an index with the same (table_id, field_ids, access_method) already exists. Returns the index_id.\n  set-data-at-path     setDataAtPath\n  set-props-and-commit setPropsAndCommit\n  provision-database-with-user provisionDatabaseWithUser\n  insert-node-at-path  insertNodeAtPath\n  update-node-at-path  updateNodeAtPath\n  set-and-commit       setAndCommit\n  provision-relation   Composable relation provisioning: creates FK fields, indexes, unique constraints, and junction tables depending on the relation_type. Supports RelationBelongsTo, RelationHasOne, RelationHasMany, and RelationManyToMany. ManyToMany uses provision_table() internally for junction table creation with full node/grant/policy support. All operations are graceful (skip existing). Returns (out_field_id, out_junction_table_id, out_source_field_id, out_target_field_id).\n  apply-rls            applyRls\n  sign-in-cross-origin signInCrossOrigin\n  create-user-database Creates a new user database with all required modules, permissions, and RLS policies.\n\nParameters:\n  - database_name: Name for the new database (required)\n  - owner_id: UUID of the owner user (required)\n  - include_invites: Include invite system (default: true)\n  - include_groups: Include group-level memberships (default: false)\n  - include_levels: Include levels/achievements (default: false)\n  - bitlen: Bit length for permission masks (default: 64)\n  - tokens_expiration: Token expiration interval (default: 30 days)\n\nReturns the database_id UUID of the newly created database.\n\nExample usage:\n  SELECT metaschema_public.create_user_database('my_app', 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'::uuid);\n  SELECT metaschema_public.create_user_database('my_app', 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'::uuid, true, true);  -- with invites and groups\n\n  extend-token-expires extendTokenExpires\n  create-api-key       createApiKey\n  send-verification-email sendVerificationEmail\n  forgot-password      forgotPassword\n  sign-up              signUp\n  request-cross-origin-token requestCrossOriginToken\n  sign-in              signIn\n  provision-table      Composable table provisioning: creates or finds a table, then creates fields (so Data* modules can reference them), applies N nodes (Data* modules), enables RLS, creates grants, creates N policies, and optionally creates table-level indexes/full_text_searches/unique_constraints. All operations are graceful (skip existing). Accepts multiple nodes and multiple policies per call, unlike secure_table_provision which is limited to one of each. Returns (out_table_id, out_fields).\n  provision-bucket     Provision an S3 bucket for a logical bucket in the database.\nReads the bucket config via RLS, then creates and configures\nthe S3 bucket with the appropriate privacy policies, CORS rules,\nand lifecycle settings.\n\n  --help, -h            Show this help message\n  --version, -v         Show version\n";
+const usage = "\ncsdk <command>\n\nCommands:\n  context               Manage API contexts\n  auth                  Manage authentication\n  org-get-managers-record orgGetManagersRecord CRUD operations\n  org-get-subordinates-record orgGetSubordinatesRecord CRUD operations\n  get-all-record       getAllRecord CRUD operations\n  app-permission       appPermission CRUD operations\n  org-permission       orgPermission CRUD operations\n  object               object CRUD operations\n  app-level-requirement appLevelRequirement CRUD operations\n  database             database CRUD operations\n  schema               schema CRUD operations\n  table                table CRUD operations\n  check-constraint     checkConstraint CRUD operations\n  field                field CRUD operations\n  spatial-relation     spatialRelation CRUD operations\n  partition            partition CRUD operations\n  foreign-key-constraint foreignKeyConstraint CRUD operations\n  full-text-search     fullTextSearch CRUD operations\n  index                index CRUD operations\n  policy               policy CRUD operations\n  primary-key-constraint primaryKeyConstraint CRUD operations\n  table-grant          tableGrant CRUD operations\n  trigger              trigger CRUD operations\n  unique-constraint    uniqueConstraint CRUD operations\n  view                 view CRUD operations\n  view-table           viewTable CRUD operations\n  view-grant           viewGrant CRUD operations\n  view-rule            viewRule CRUD operations\n  embedding-chunk      embeddingChunk CRUD operations\n  secure-table-provision secureTableProvision CRUD operations\n  relation-provision   relationProvision CRUD operations\n  session-secrets-module sessionSecretsModule CRUD operations\n  identity-providers-module identityProvidersModule CRUD operations\n  realtime-module      realtimeModule CRUD operations\n  schema-grant         schemaGrant CRUD operations\n  default-privilege    defaultPrivilege CRUD operations\n  enum                 enum CRUD operations\n  function             function CRUD operations\n  api-schema           apiSchema CRUD operations\n  api-module           apiModule CRUD operations\n  domain               domain CRUD operations\n  site-metadatum       siteMetadatum CRUD operations\n  site-module          siteModule CRUD operations\n  site-theme           siteTheme CRUD operations\n  cors-setting         corsSetting CRUD operations\n  trigger-function     triggerFunction CRUD operations\n  database-transfer    databaseTransfer CRUD operations\n  api                  api CRUD operations\n  site                 site CRUD operations\n  app                  app CRUD operations\n  api-setting          apiSetting CRUD operations\n  connected-accounts-module connectedAccountsModule CRUD operations\n  crypto-addresses-module cryptoAddressesModule CRUD operations\n  crypto-auth-module   cryptoAuthModule CRUD operations\n  default-ids-module   defaultIdsModule CRUD operations\n  denormalized-table-field denormalizedTableField CRUD operations\n  emails-module        emailsModule CRUD operations\n  encrypted-secrets-module encryptedSecretsModule CRUD operations\n  invites-module       invitesModule CRUD operations\n  levels-module        levelsModule CRUD operations\n  limits-module        limitsModule CRUD operations\n  membership-types-module membershipTypesModule CRUD operations\n  memberships-module   membershipsModule CRUD operations\n  permissions-module   permissionsModule CRUD operations\n  phone-numbers-module phoneNumbersModule CRUD operations\n  profiles-module      profilesModule CRUD operations\n  secrets-module       secretsModule CRUD operations\n  sessions-module      sessionsModule CRUD operations\n  user-auth-module     userAuthModule CRUD operations\n  users-module         usersModule CRUD operations\n  blueprint            blueprint CRUD operations\n  blueprint-template   blueprintTemplate CRUD operations\n  blueprint-construction blueprintConstruction CRUD operations\n  storage-module       storageModule CRUD operations\n  entity-type-provision entityTypeProvision CRUD operations\n  webauthn-credentials-module webauthnCredentialsModule CRUD operations\n  webauthn-auth-module webauthnAuthModule CRUD operations\n  notifications-module notificationsModule CRUD operations\n  database-provision-module databaseProvisionModule CRUD operations\n  app-admin-grant      appAdminGrant CRUD operations\n  app-owner-grant      appOwnerGrant CRUD operations\n  app-grant            appGrant CRUD operations\n  org-membership       orgMembership CRUD operations\n  org-member           orgMember CRUD operations\n  org-admin-grant      orgAdminGrant CRUD operations\n  org-owner-grant      orgOwnerGrant CRUD operations\n  org-member-profile   orgMemberProfile CRUD operations\n  org-grant            orgGrant CRUD operations\n  org-chart-edge       orgChartEdge CRUD operations\n  org-chart-edge-grant orgChartEdgeGrant CRUD operations\n  org-permission-default orgPermissionDefault CRUD operations\n  app-limit            appLimit CRUD operations\n  app-limit-credit     appLimitCredit CRUD operations\n  app-limit-credit-code-item appLimitCreditCodeItem CRUD operations\n  app-limit-credit-redemption appLimitCreditRedemption CRUD operations\n  org-limit            orgLimit CRUD operations\n  org-limit-credit     orgLimitCredit CRUD operations\n  org-limit-aggregate  orgLimitAggregate CRUD operations\n  app-step             appStep CRUD operations\n  app-achievement      appAchievement CRUD operations\n  app-level            appLevel CRUD operations\n  email                email CRUD operations\n  phone-number         phoneNumber CRUD operations\n  crypto-address       cryptoAddress CRUD operations\n  webauthn-credential  webauthnCredential CRUD operations\n  app-invite           appInvite CRUD operations\n  app-claimed-invite   appClaimedInvite CRUD operations\n  org-invite           orgInvite CRUD operations\n  org-claimed-invite   orgClaimedInvite CRUD operations\n  audit-log            auditLog CRUD operations\n  agent-thread         agentThread CRUD operations\n  agent-message        agentMessage CRUD operations\n  agent-task           agentTask CRUD operations\n  role-type            roleType CRUD operations\n  identity-provider    identityProvider CRUD operations\n  ref                  ref CRUD operations\n  store                store CRUD operations\n  app-permission-default appPermissionDefault CRUD operations\n  app-limit-credit-code appLimitCreditCode CRUD operations\n  app-limit-caps-default appLimitCapsDefault CRUD operations\n  org-limit-caps-default orgLimitCapsDefault CRUD operations\n  app-limit-cap        appLimitCap CRUD operations\n  org-limit-cap        orgLimitCap CRUD operations\n  membership-type      membershipType CRUD operations\n  migrate-file         migrateFile CRUD operations\n  devices-module       devicesModule CRUD operations\n  node-type-registry   nodeTypeRegistry CRUD operations\n  app-limit-default    appLimitDefault CRUD operations\n  org-limit-default    orgLimitDefault CRUD operations\n  user-connected-account userConnectedAccount CRUD operations\n  commit               commit CRUD operations\n  pubkey-setting       pubkeySetting CRUD operations\n  rate-limits-module   rateLimitsModule CRUD operations\n  app-membership-default appMembershipDefault CRUD operations\n  org-membership-default orgMembershipDefault CRUD operations\n  rls-setting          rlsSetting CRUD operations\n  app-limit-event      appLimitEvent CRUD operations\n  org-limit-event      orgLimitEvent CRUD operations\n  rls-module           rlsModule CRUD operations\n  database-setting     databaseSetting CRUD operations\n  plans-module         plansModule CRUD operations\n  sql-action           sqlAction CRUD operations\n  billing-module       billingModule CRUD operations\n  ast-migration        astMigration CRUD operations\n  user                 user CRUD operations\n  org-membership-setting orgMembershipSetting CRUD operations\n  webauthn-setting     webauthnSetting CRUD operations\n  app-membership       appMembership CRUD operations\n  billing-provider-module billingProviderModule CRUD operations\n  hierarchy-module     hierarchyModule CRUD operations\n  current-user-id      currentUserId\n  current-user-agent   currentUserAgent\n  current-ip-address   currentIpAddress\n  require-step-up      requireStepUp\n  app-permissions-get-padded-mask appPermissionsGetPaddedMask\n  org-permissions-get-padded-mask orgPermissionsGetPaddedMask\n  steps-achieved       stepsAchieved\n  rev-parse            revParse\n  resolve-blueprint-field Resolves a field_name within a given table_id to a field_id. Throws if no match is found. Used by construct_blueprint to translate user-authored field names (e.g. \"location\") into field UUIDs for downstream provisioning procedures. table_id must already be resolved (via resolve_blueprint_table) before calling this.\n  org-is-manager-of    orgIsManagerOf\n  app-permissions-get-mask appPermissionsGetMask\n  org-permissions-get-mask orgPermissionsGetMask\n  resolve-blueprint-table Resolves a table_name (with optional schema_name) to a table_id. Resolution order: (1) if schema_name provided, exact lookup via metaschema_public.schema.name + metaschema_public.table; (2) check local table_map (tables created in current blueprint); (3) search metaschema_public.table by name across all schemas; (4) if multiple matches, throw ambiguous error asking for schema_name; (5) if no match, throw not-found error.\n  app-permissions-get-mask-by-names appPermissionsGetMaskByNames\n  org-permissions-get-mask-by-names orgPermissionsGetMaskByNames\n  app-permissions-get-by-mask Reads and enables pagination through a set of `AppPermission`.\n  org-permissions-get-by-mask Reads and enables pagination through a set of `OrgPermission`.\n  get-all-objects-from-root Reads and enables pagination through a set of `Object`.\n  get-path-objects-from-root Reads and enables pagination through a set of `Object`.\n  get-object-at-path   getObjectAtPath\n  steps-required       Reads and enables pagination through a set of `AppLevelRequirement`.\n  current-user         currentUser\n  send-account-deletion-email sendAccountDeletionEmail\n  sign-out             signOut\n  accept-database-transfer acceptDatabaseTransfer\n  cancel-database-transfer cancelDatabaseTransfer\n  reject-database-transfer rejectDatabaseTransfer\n  disconnect-account   disconnectAccount\n  revoke-api-key       revokeApiKey\n  revoke-session       revokeSession\n  verify-password      verifyPassword\n  verify-totp          verifyTotp\n  submit-app-invite-code submitAppInviteCode\n  submit-org-invite-code submitOrgInviteCode\n  check-password       checkPassword\n  confirm-delete-account confirmDeleteAccount\n  set-password         setPassword\n  verify-email         verifyEmail\n  freeze-objects       freezeObjects\n  init-empty-repo      initEmptyRepo\n  construct-blueprint  Executes a blueprint definition by delegating to provision_* procedures. Creates a blueprint_construction record to track the attempt. Six phases: (0) entity_type_provision for each membership_type entry \u2014 provisions entity tables, membership modules, and security, (1) provision_table() for each table with nodes[], fields[], policies[], and grants (table-level indexes/fts/unique_constraints are deferred), (2) provision_relation() for each relation, (3) provision_index() for top-level + deferred indexes, (4) provision_full_text_search() for top-level + deferred FTS, (5) provision_unique_constraint() for top-level + deferred unique constraints. Phase 0 entity tables are added to the table_map so subsequent phases can reference them by name. Table-level indexes/fts/unique_constraints are deferred to phases 3-5 so they can reference columns created by relations in phase 2. Returns the construction record ID on success, NULL on failure.\n  provision-new-user   provisionNewUser\n  reset-password       resetPassword\n  remove-node-at-path  removeNodeAtPath\n  copy-template-to-blueprint Creates a new blueprint by copying a template definition. Checks visibility: owners can always copy their own templates, others require public visibility. Increments the template copy_count. Returns the new blueprint ID.\n  provision-spatial-relation Idempotent provisioner for metaschema_public.spatial_relation. Inserts a row declaring a spatial predicate between two geometry/geography columns (owner and target). Called from construct_blueprint when a relation entry has $type=RelationSpatial. Graceful: re-running with the same (source_table_id, name) returns the existing id without modifying the row. Operator whitelist and st_dwithin \u2194 param_name pairing are enforced by the spatial_relation table CHECKs. Both fields must already exist \u2014 this is a metadata-only insert.\n  bootstrap-user       bootstrapUser\n  set-field-order      setFieldOrder\n  append-field-smart-tags appendFieldSmartTags\n  append-table-smart-tags appendTableSmartTags\n  provision-unique-constraint Creates a unique constraint on a table. Accepts a jsonb definition with columns (array of field names). Graceful: skips if the exact same unique constraint already exists.\n  provision-full-text-search Creates a full-text search configuration on a table. Accepts a jsonb definition with field (tsvector column name) and sources (array of {field, weight, lang}). Graceful: skips if FTS config already exists for the same (table_id, field_id). Returns the fts_id.\n  provision-index      Creates an index on a table. Accepts a jsonb definition with columns (array of names or single column string), access_method (default BTREE), is_unique, op_classes, options, and name (auto-generated if omitted). Graceful: skips if an index with the same (table_id, field_ids, access_method) already exists. Returns the index_id.\n  set-data-at-path     setDataAtPath\n  set-props-and-commit setPropsAndCommit\n  provision-database-with-user provisionDatabaseWithUser\n  insert-node-at-path  insertNodeAtPath\n  update-node-at-path  updateNodeAtPath\n  set-and-commit       setAndCommit\n  provision-relation   Composable relation provisioning: creates FK fields, indexes, unique constraints, and junction tables depending on the relation_type. Supports RelationBelongsTo, RelationHasOne, RelationHasMany, and RelationManyToMany. ManyToMany uses provision_table() internally for junction table creation with full node/grant/policy support. All operations are graceful (skip existing). Returns (out_field_id, out_junction_table_id, out_source_field_id, out_target_field_id).\n  apply-rls            applyRls\n  sign-in-cross-origin signInCrossOrigin\n  create-user-database Creates a new user database with all required modules, permissions, and RLS policies.\n\nParameters:\n  - database_name: Name for the new database (required)\n  - owner_id: UUID of the owner user (required)\n  - include_invites: Include invite system (default: true)\n  - include_groups: Include group-level memberships (default: false)\n  - include_levels: Include levels/achievements (default: false)\n  - bitlen: Bit length for permission masks (default: 64)\n  - tokens_expiration: Token expiration interval (default: 30 days)\n\nReturns the database_id UUID of the newly created database.\n\nExample usage:\n  SELECT metaschema_public.create_user_database('my_app', 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'::uuid);\n  SELECT metaschema_public.create_user_database('my_app', 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'::uuid, true, true);  -- with invites and groups\n\n  extend-token-expires extendTokenExpires\n  create-api-key       createApiKey\n  send-verification-email sendVerificationEmail\n  forgot-password      forgotPassword\n  sign-up              signUp\n  request-cross-origin-token requestCrossOriginToken\n  sign-in              signIn\n  provision-table      Composable table provisioning: creates or finds a table, then creates fields (so Data* modules can reference them), applies N nodes (Data* modules), enables RLS, creates grants, creates N policies, and optionally creates table-level indexes/full_text_searches/unique_constraints. All operations are graceful (skip existing). Accepts multiple nodes and multiple policies per call, unlike secure_table_provision which is limited to one of each. Returns (out_table_id, out_fields).\n  provision-bucket     Provision an S3 bucket for a logical bucket in the database.\nReads the bucket config via RLS, then creates and configures\nthe S3 bucket with the appropriate privacy policies, CORS rules,\nand lifecycle settings.\n\n  --help, -h            Show this help message\n  --version, -v         Show version\n";
 export const commands = async (argv, prompter, options) => {
     if (argv.help || argv.h) {
         console.log(usage);

package/esm/public/cli/executor.d.ts

@@ -391,10 +391,15 @@ export declare function getClient(contextName?: string): {
         } & import("..").StrictSelect<S, import("../orm/input-types").SetFieldOrderPayloadSelect>) => import("..").QueryBuilder<{
             setFieldOrder: import("..").InferSelectResult<import("../orm/input-types").SetFieldOrderPayload, S> | null;
         }>;
-        appendSmartTags: <S extends import("../orm/input-types").AppendSmartTagsPayloadSelect>(args: import("../orm/mutation").AppendSmartTagsVariables, options: {
+        appendFieldSmartTags: <S extends import("../orm/input-types").AppendFieldSmartTagsPayloadSelect>(args: import("../orm/mutation").AppendFieldSmartTagsVariables, options: {
             select: S;
-        } & import("..").StrictSelect<S, import("../orm/input-types").AppendSmartTagsPayloadSelect>) => import("..").QueryBuilder<{
-            appendSmartTags: import("..").InferSelectResult<import("../orm/input-types").AppendSmartTagsPayload, S> | null;
+        } & import("..").StrictSelect<S, import("../orm/input-types").AppendFieldSmartTagsPayloadSelect>) => import("..").QueryBuilder<{
+            appendFieldSmartTags: import("..").InferSelectResult<import("../orm/input-types").AppendFieldSmartTagsPayload, S> | null;
+        }>;
+        appendTableSmartTags: <S extends import("../orm/input-types").AppendTableSmartTagsPayloadSelect>(args: import("../orm/mutation").AppendTableSmartTagsVariables, options: {
+            select: S;
+        } & import("..").StrictSelect<S, import("../orm/input-types").AppendTableSmartTagsPayloadSelect>) => import("..").QueryBuilder<{
+            appendTableSmartTags: import("..").InferSelectResult<import("../orm/input-types").AppendTableSmartTagsPayload, S> | null;
         }>;
         provisionUniqueConstraint: <S extends import("../orm/input-types").ProvisionUniqueConstraintPayloadSelect>(args: import("../orm/mutation").ProvisionUniqueConstraintVariables, options: {
             select: S;

package/esm/public/orm/client.d.ts

@@ -4,7 +4,10 @@
  * DO NOT EDIT - changes will be overwritten
  */
 import type { GraphQLAdapter, GraphQLError, QueryResult } from '@constructive-io/graphql-query/runtime';
+import type { ConnectionState, ConnectionStateListener, RealtimeConfig, SubscriptionEvent, SubscriptionFieldMeta, Unsubscribe } from './realtime';
 export type { GraphQLAdapter, GraphQLError, QueryResult, } from '@constructive-io/graphql-query/runtime';
+export type { ConnectionState, ConnectionStateListener, RealtimeConfig, SubscribeOptions, SubscriptionEvent, SubscriptionFieldMeta, SubscriptionOperation, Unsubscribe, WsClient, } from './realtime';
+export { RealtimeManager } from './realtime';
 /**
  * Default adapter that uses fetch for HTTP requests.
  *
@@ -41,6 +44,12 @@ export interface OrmClientConfig {
     fetch?: typeof globalThis.fetch;
     /** Custom adapter for GraphQL execution (overrides endpoint/headers/fetch) */
     adapter?: GraphQLAdapter;
+    /**
+     * Optional realtime (WebSocket) configuration.
+     * When provided, enables subscription methods on models.
+     * The WebSocket connection is created lazily on first subscribe().
+     */
+    realtime?: RealtimeConfig;
 }
 /**
  * Error thrown when GraphQL request fails
@@ -52,8 +61,19 @@ export declare class GraphQLRequestError extends Error {
 }
 export declare class OrmClient {
     private adapter;
+    private realtimeManager?;
     constructor(config: OrmClientConfig);
     execute<T>(document: string, variables?: Record<string, unknown>): Promise<QueryResult<T>>;
+    /**
+     * Subscribe to a GraphQL subscription operation.
+     * Used by generated model subscribe() methods.
+     * @throws Error if realtime is not configured
+     */
+    subscribe<T>(meta: SubscriptionFieldMeta, document: string, variables: Record<string, unknown>, options: {
+        onEvent: (event: SubscriptionEvent<T>) => void;
+        onError?: (error: Error) => void;
+        onComplete?: () => void;
+    }): Unsubscribe;
     /**
      * Set headers for requests.
      * Only works if the adapter supports headers.
@@ -64,4 +84,14 @@ export declare class OrmClient {
      * Returns empty string if the adapter doesn't have an endpoint.
      */
     getEndpoint(): string;
+    /** Get current WebSocket connection state */
+    getConnectionState(): ConnectionState;
+    /** Register a listener for WebSocket connection state changes */
+    onConnectionStateChange(listener: ConnectionStateListener): Unsubscribe;
+    /** Number of active subscriptions */
+    getActiveSubscriptionCount(): number;
+    /** Whether realtime is configured */
+    get isRealtimeEnabled(): boolean;
+    /** Dispose the realtime manager (close WebSocket) */
+    dispose(): void;
 }

package/esm/public/orm/client.js

@@ -1,4 +1,6 @@
 import { createFetch } from '@constructive-io/graphql-query/runtime';
+import { RealtimeManager } from './realtime';
+export { RealtimeManager } from './realtime';
 /**
  * Default adapter that uses fetch for HTTP requests.
  *
@@ -73,6 +75,7 @@ export class GraphQLRequestError extends Error {
 }
 export class OrmClient {
     adapter;
+    realtimeManager;
     constructor(config) {
         if (config.adapter) {
             this.adapter = config.adapter;
@@ -83,10 +86,24 @@ export class OrmClient {
         else {
             throw new Error('OrmClientConfig requires either an endpoint or a custom adapter');
         }
+        if (config.realtime) {
+            this.realtimeManager = new RealtimeManager(config.realtime);
+        }
     }
     async execute(document, variables) {
         return this.adapter.execute(document, variables);
     }
+    /**
+     * Subscribe to a GraphQL subscription operation.
+     * Used by generated model subscribe() methods.
+     * @throws Error if realtime is not configured
+     */
+    subscribe(meta, document, variables, options) {
+        if (!this.realtimeManager) {
+            throw new Error('Realtime not configured. Pass a `realtime` option to createClient() to enable subscriptions.');
+        }
+        return this.realtimeManager.subscribe(meta, document, variables, options);
+    }
     /**
      * Set headers for requests.
      * Only works if the adapter supports headers.
@@ -103,4 +120,26 @@ export class OrmClient {
     getEndpoint() {
         return this.adapter.getEndpoint?.() ?? '';
     }
+    /** Get current WebSocket connection state */
+    getConnectionState() {
+        return this.realtimeManager?.getConnectionState() ?? 'disconnected';
+    }
+    /** Register a listener for WebSocket connection state changes */
+    onConnectionStateChange(listener) {
+        if (!this.realtimeManager)
+            return () => { };
+        return this.realtimeManager.onConnectionStateChange(listener);
+    }
+    /** Number of active subscriptions */
+    getActiveSubscriptionCount() {
+        return this.realtimeManager?.getActiveSubscriptionCount() ?? 0;
+    }
+    /** Whether realtime is configured */
+    get isRealtimeEnabled() {
+        return this.realtimeManager !== undefined;
+    }
+    /** Dispose the realtime manager (close WebSocket) */
+    dispose() {
+        this.realtimeManager?.dispose();
+    }
 }

package/esm/public/orm/index.d.ts

@@ -570,10 +570,15 @@ export declare function createClient(config: OrmClientConfig): {
         } & import("./select-types").StrictSelect<S, import("./input-types").SetFieldOrderPayloadSelect>) => import("./query-builder").QueryBuilder<{
             setFieldOrder: import("./select-types").InferSelectResult<import("./input-types").SetFieldOrderPayload, S> | null;
         }>;
-        appendSmartTags: <S extends import("./input-types").AppendSmartTagsPayloadSelect>(args: import("./mutation").AppendSmartTagsVariables, options: {
+        appendFieldSmartTags: <S extends import("./input-types").AppendFieldSmartTagsPayloadSelect>(args: import("./mutation").AppendFieldSmartTagsVariables, options: {
             select: S;
-        } & import("./select-types").StrictSelect<S, import("./input-types").AppendSmartTagsPayloadSelect>) => import("./query-builder").QueryBuilder<{
-            appendSmartTags: import("./select-types").InferSelectResult<import("./input-types").AppendSmartTagsPayload, S> | null;
+        } & import("./select-types").StrictSelect<S, import("./input-types").AppendFieldSmartTagsPayloadSelect>) => import("./query-builder").QueryBuilder<{
+            appendFieldSmartTags: import("./select-types").InferSelectResult<import("./input-types").AppendFieldSmartTagsPayload, S> | null;
+        }>;
+        appendTableSmartTags: <S extends import("./input-types").AppendTableSmartTagsPayloadSelect>(args: import("./mutation").AppendTableSmartTagsVariables, options: {
+            select: S;
+        } & import("./select-types").StrictSelect<S, import("./input-types").AppendTableSmartTagsPayloadSelect>) => import("./query-builder").QueryBuilder<{
+            appendTableSmartTags: import("./select-types").InferSelectResult<import("./input-types").AppendTableSmartTagsPayload, S> | null;
         }>;
         provisionUniqueConstraint: <S extends import("./input-types").ProvisionUniqueConstraintPayloadSelect>(args: import("./mutation").ProvisionUniqueConstraintVariables, options: {
             select: S;

package/esm/public/orm/input-types.d.ts

@@ -19201,7 +19201,12 @@ export interface SetFieldOrderInput {
     clientMutationId?: string;
     fieldIds?: string[];
 }
-export interface AppendSmartTagsInput {
+export interface AppendFieldSmartTagsInput {
+    clientMutationId?: string;
+    pFieldId?: string;
+    pTags?: Record<string, unknown>;
+}
+export interface AppendTableSmartTagsInput {
     clientMutationId?: string;
     pTableId?: string;
     pTags?: Record<string, unknown>;
@@ -27717,10 +27722,16 @@ export interface SetFieldOrderPayload {
 export type SetFieldOrderPayloadSelect = {
     clientMutationId?: boolean;
 };
-export interface AppendSmartTagsPayload {
+export interface AppendFieldSmartTagsPayload {
+    clientMutationId?: string | null;
+}
+export type AppendFieldSmartTagsPayloadSelect = {
+    clientMutationId?: boolean;
+};
+export interface AppendTableSmartTagsPayload {
     clientMutationId?: string | null;
 }
-export type AppendSmartTagsPayloadSelect = {
+export type AppendTableSmartTagsPayloadSelect = {
     clientMutationId?: boolean;
 };
 export interface ProvisionUniqueConstraintPayload {

package/esm/public/orm/mutation/index.d.ts

@@ -6,7 +6,7 @@
 import { OrmClient } from '../client';
 import { QueryBuilder } from '../query-builder';
 import type { InferSelectResult, StrictSelect } from '../select-types';
-import type { SendAccountDeletionEmailInput, SignOutInput, AcceptDatabaseTransferInput, CancelDatabaseTransferInput, RejectDatabaseTransferInput, DisconnectAccountInput, RevokeApiKeyInput, RevokeSessionInput, VerifyPasswordInput, VerifyTotpInput, SubmitAppInviteCodeInput, SubmitOrgInviteCodeInput, CheckPasswordInput, ConfirmDeleteAccountInput, SetPasswordInput, VerifyEmailInput, FreezeObjectsInput, InitEmptyRepoInput, ConstructBlueprintInput, ProvisionNewUserInput, ResetPasswordInput, RemoveNodeAtPathInput, CopyTemplateToBlueprintInput, ProvisionSpatialRelationInput, BootstrapUserInput, SetFieldOrderInput, AppendSmartTagsInput, ProvisionUniqueConstraintInput, ProvisionFullTextSearchInput, ProvisionIndexInput, SetDataAtPathInput, SetPropsAndCommitInput, ProvisionDatabaseWithUserInput, InsertNodeAtPathInput, UpdateNodeAtPathInput, SetAndCommitInput, ProvisionRelationInput, ApplyRlsInput, SignInCrossOriginInput, CreateUserDatabaseInput, ExtendTokenExpiresInput, CreateApiKeyInput, SendVerificationEmailInput, ForgotPasswordInput, SignUpInput, RequestCrossOriginTokenInput, SignInInput, ProvisionTableInput, ProvisionBucketInput, SendAccountDeletionEmailPayload, SignOutPayload, AcceptDatabaseTransferPayload, CancelDatabaseTransferPayload, RejectDatabaseTransferPayload, DisconnectAccountPayload, RevokeApiKeyPayload, RevokeSessionPayload, VerifyPasswordPayload, VerifyTotpPayload, SubmitAppInviteCodePayload, SubmitOrgInviteCodePayload, CheckPasswordPayload, ConfirmDeleteAccountPayload, SetPasswordPayload, VerifyEmailPayload, FreezeObjectsPayload, InitEmptyRepoPayload, ConstructBlueprintPayload, ProvisionNewUserPayload, ResetPasswordPayload, RemoveNodeAtPathPayload, CopyTemplateToBlueprintPayload, ProvisionSpatialRelationPayload, BootstrapUserPayload, SetFieldOrderPayload, AppendSmartTagsPayload, ProvisionUniqueConstraintPayload, ProvisionFullTextSearchPayload, ProvisionIndexPayload, SetDataAtPathPayload, SetPropsAndCommitPayload, ProvisionDatabaseWithUserPayload, InsertNodeAtPathPayload, UpdateNodeAtPathPayload, SetAndCommitPayload, ProvisionRelationPayload, ApplyRlsPayload, SignInCrossOriginPayload, CreateUserDatabasePayload, ExtendTokenExpiresPayload, CreateApiKeyPayload, SendVerificationEmailPayload, ForgotPasswordPayload, SignUpPayload, RequestCrossOriginTokenPayload, SignInPayload, ProvisionTablePayload, ProvisionBucketPayload, SendAccountDeletionEmailPayloadSelect, SignOutPayloadSelect, AcceptDatabaseTransferPayloadSelect, CancelDatabaseTransferPayloadSelect, RejectDatabaseTransferPayloadSelect, DisconnectAccountPayloadSelect, RevokeApiKeyPayloadSelect, RevokeSessionPayloadSelect, VerifyPasswordPayloadSelect, VerifyTotpPayloadSelect, SubmitAppInviteCodePayloadSelect, SubmitOrgInviteCodePayloadSelect, CheckPasswordPayloadSelect, ConfirmDeleteAccountPayloadSelect, SetPasswordPayloadSelect, VerifyEmailPayloadSelect, FreezeObjectsPayloadSelect, InitEmptyRepoPayloadSelect, ConstructBlueprintPayloadSelect, ProvisionNewUserPayloadSelect, ResetPasswordPayloadSelect, RemoveNodeAtPathPayloadSelect, CopyTemplateToBlueprintPayloadSelect, ProvisionSpatialRelationPayloadSelect, BootstrapUserPayloadSelect, SetFieldOrderPayloadSelect, AppendSmartTagsPayloadSelect, ProvisionUniqueConstraintPayloadSelect, ProvisionFullTextSearchPayloadSelect, ProvisionIndexPayloadSelect, SetDataAtPathPayloadSelect, SetPropsAndCommitPayloadSelect, ProvisionDatabaseWithUserPayloadSelect, InsertNodeAtPathPayloadSelect, UpdateNodeAtPathPayloadSelect, SetAndCommitPayloadSelect, ProvisionRelationPayloadSelect, ApplyRlsPayloadSelect, SignInCrossOriginPayloadSelect, CreateUserDatabasePayloadSelect, ExtendTokenExpiresPayloadSelect, CreateApiKeyPayloadSelect, SendVerificationEmailPayloadSelect, ForgotPasswordPayloadSelect, SignUpPayloadSelect, RequestCrossOriginTokenPayloadSelect, SignInPayloadSelect, ProvisionTablePayloadSelect, ProvisionBucketPayloadSelect } from '../input-types';
+import type { SendAccountDeletionEmailInput, SignOutInput, AcceptDatabaseTransferInput, CancelDatabaseTransferInput, RejectDatabaseTransferInput, DisconnectAccountInput, RevokeApiKeyInput, RevokeSessionInput, VerifyPasswordInput, VerifyTotpInput, SubmitAppInviteCodeInput, SubmitOrgInviteCodeInput, CheckPasswordInput, ConfirmDeleteAccountInput, SetPasswordInput, VerifyEmailInput, FreezeObjectsInput, InitEmptyRepoInput, ConstructBlueprintInput, ProvisionNewUserInput, ResetPasswordInput, RemoveNodeAtPathInput, CopyTemplateToBlueprintInput, ProvisionSpatialRelationInput, BootstrapUserInput, SetFieldOrderInput, AppendFieldSmartTagsInput, AppendTableSmartTagsInput, ProvisionUniqueConstraintInput, ProvisionFullTextSearchInput, ProvisionIndexInput, SetDataAtPathInput, SetPropsAndCommitInput, ProvisionDatabaseWithUserInput, InsertNodeAtPathInput, UpdateNodeAtPathInput, SetAndCommitInput, ProvisionRelationInput, ApplyRlsInput, SignInCrossOriginInput, CreateUserDatabaseInput, ExtendTokenExpiresInput, CreateApiKeyInput, SendVerificationEmailInput, ForgotPasswordInput, SignUpInput, RequestCrossOriginTokenInput, SignInInput, ProvisionTableInput, ProvisionBucketInput, SendAccountDeletionEmailPayload, SignOutPayload, AcceptDatabaseTransferPayload, CancelDatabaseTransferPayload, RejectDatabaseTransferPayload, DisconnectAccountPayload, RevokeApiKeyPayload, RevokeSessionPayload, VerifyPasswordPayload, VerifyTotpPayload, SubmitAppInviteCodePayload, SubmitOrgInviteCodePayload, CheckPasswordPayload, ConfirmDeleteAccountPayload, SetPasswordPayload, VerifyEmailPayload, FreezeObjectsPayload, InitEmptyRepoPayload, ConstructBlueprintPayload, ProvisionNewUserPayload, ResetPasswordPayload, RemoveNodeAtPathPayload, CopyTemplateToBlueprintPayload, ProvisionSpatialRelationPayload, BootstrapUserPayload, SetFieldOrderPayload, AppendFieldSmartTagsPayload, AppendTableSmartTagsPayload, ProvisionUniqueConstraintPayload, ProvisionFullTextSearchPayload, ProvisionIndexPayload, SetDataAtPathPayload, SetPropsAndCommitPayload, ProvisionDatabaseWithUserPayload, InsertNodeAtPathPayload, UpdateNodeAtPathPayload, SetAndCommitPayload, ProvisionRelationPayload, ApplyRlsPayload, SignInCrossOriginPayload, CreateUserDatabasePayload, ExtendTokenExpiresPayload, CreateApiKeyPayload, SendVerificationEmailPayload, ForgotPasswordPayload, SignUpPayload, RequestCrossOriginTokenPayload, SignInPayload, ProvisionTablePayload, ProvisionBucketPayload, SendAccountDeletionEmailPayloadSelect, SignOutPayloadSelect, AcceptDatabaseTransferPayloadSelect, CancelDatabaseTransferPayloadSelect, RejectDatabaseTransferPayloadSelect, DisconnectAccountPayloadSelect, RevokeApiKeyPayloadSelect, RevokeSessionPayloadSelect, VerifyPasswordPayloadSelect, VerifyTotpPayloadSelect, SubmitAppInviteCodePayloadSelect, SubmitOrgInviteCodePayloadSelect, CheckPasswordPayloadSelect, ConfirmDeleteAccountPayloadSelect, SetPasswordPayloadSelect, VerifyEmailPayloadSelect, FreezeObjectsPayloadSelect, InitEmptyRepoPayloadSelect, ConstructBlueprintPayloadSelect, ProvisionNewUserPayloadSelect, ResetPasswordPayloadSelect, RemoveNodeAtPathPayloadSelect, CopyTemplateToBlueprintPayloadSelect, ProvisionSpatialRelationPayloadSelect, BootstrapUserPayloadSelect, SetFieldOrderPayloadSelect, AppendFieldSmartTagsPayloadSelect, AppendTableSmartTagsPayloadSelect, ProvisionUniqueConstraintPayloadSelect, ProvisionFullTextSearchPayloadSelect, ProvisionIndexPayloadSelect, SetDataAtPathPayloadSelect, SetPropsAndCommitPayloadSelect, ProvisionDatabaseWithUserPayloadSelect, InsertNodeAtPathPayloadSelect, UpdateNodeAtPathPayloadSelect, SetAndCommitPayloadSelect, ProvisionRelationPayloadSelect, ApplyRlsPayloadSelect, SignInCrossOriginPayloadSelect, CreateUserDatabasePayloadSelect, ExtendTokenExpiresPayloadSelect, CreateApiKeyPayloadSelect, SendVerificationEmailPayloadSelect, ForgotPasswordPayloadSelect, SignUpPayloadSelect, RequestCrossOriginTokenPayloadSelect, SignInPayloadSelect, ProvisionTablePayloadSelect, ProvisionBucketPayloadSelect } from '../input-types';
 export interface SendAccountDeletionEmailVariables {
     input: SendAccountDeletionEmailInput;
 }
@@ -97,8 +97,11 @@ export interface BootstrapUserVariables {
 export interface SetFieldOrderVariables {
     input: SetFieldOrderInput;
 }
-export interface AppendSmartTagsVariables {
-    input: AppendSmartTagsInput;
+export interface AppendFieldSmartTagsVariables {
+    input: AppendFieldSmartTagsInput;
+}
+export interface AppendTableSmartTagsVariables {
+    input: AppendTableSmartTagsInput;
 }
 /**
  * Variables for provisionUniqueConstraint
@@ -343,10 +346,15 @@ export declare function createMutationOperations(client: OrmClient): {
     } & StrictSelect<S, SetFieldOrderPayloadSelect>) => QueryBuilder<{
         setFieldOrder: InferSelectResult<SetFieldOrderPayload, S> | null;
     }>;
-    appendSmartTags: <S extends AppendSmartTagsPayloadSelect>(args: AppendSmartTagsVariables, options: {
+    appendFieldSmartTags: <S extends AppendFieldSmartTagsPayloadSelect>(args: AppendFieldSmartTagsVariables, options: {
+        select: S;
+    } & StrictSelect<S, AppendFieldSmartTagsPayloadSelect>) => QueryBuilder<{
+        appendFieldSmartTags: InferSelectResult<AppendFieldSmartTagsPayload, S> | null;
+    }>;
+    appendTableSmartTags: <S extends AppendTableSmartTagsPayloadSelect>(args: AppendTableSmartTagsVariables, options: {
         select: S;
-    } & StrictSelect<S, AppendSmartTagsPayloadSelect>) => QueryBuilder<{
-        appendSmartTags: InferSelectResult<AppendSmartTagsPayload, S> | null;
+    } & StrictSelect<S, AppendTableSmartTagsPayloadSelect>) => QueryBuilder<{
+        appendTableSmartTags: InferSelectResult<AppendTableSmartTagsPayload, S> | null;
     }>;
     provisionUniqueConstraint: <S extends ProvisionUniqueConstraintPayloadSelect>(args: ProvisionUniqueConstraintVariables, options: {
         select: S;

package/esm/public/orm/mutation/index.js

@@ -314,17 +314,29 @@ export function createMutationOperations(client) {
                 },
             ], connectionFieldsMap, 'SetFieldOrderPayload'),
         }),
-        appendSmartTags: (args, options) => new QueryBuilder({
+        appendFieldSmartTags: (args, options) => new QueryBuilder({
             client,
             operation: 'mutation',
-            operationName: 'AppendSmartTags',
-            fieldName: 'appendSmartTags',
-            ...buildCustomDocument('mutation', 'AppendSmartTags', 'appendSmartTags', options.select, args, [
+            operationName: 'AppendFieldSmartTags',
+            fieldName: 'appendFieldSmartTags',
+            ...buildCustomDocument('mutation', 'AppendFieldSmartTags', 'appendFieldSmartTags', options.select, args, [
                 {
                     name: 'input',
-                    type: 'AppendSmartTagsInput!',
+                    type: 'AppendFieldSmartTagsInput!',
                 },
-            ], connectionFieldsMap, 'AppendSmartTagsPayload'),
+            ], connectionFieldsMap, 'AppendFieldSmartTagsPayload'),
+        }),
+        appendTableSmartTags: (args, options) => new QueryBuilder({
+            client,
+            operation: 'mutation',
+            operationName: 'AppendTableSmartTags',
+            fieldName: 'appendTableSmartTags',
+            ...buildCustomDocument('mutation', 'AppendTableSmartTags', 'appendTableSmartTags', options.select, args, [
+                {
+                    name: 'input',
+                    type: 'AppendTableSmartTagsInput!',
+                },
+            ], connectionFieldsMap, 'AppendTableSmartTagsPayload'),
         }),
         provisionUniqueConstraint: (args, options) => new QueryBuilder({
             client,

package/esm/public/orm/realtime.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Realtime Manager - WebSocket subscription support
+ * @generated by @constructive-io/graphql-codegen
+ * DO NOT EDIT - changes will be overwritten
+ */
+interface WsGraphQLError {
+    readonly message: string;
+    readonly [key: string]: unknown;
+}
+interface WsExecutionResult<TData = Record<string, unknown>> {
+    data?: TData | null;
+    errors?: readonly WsGraphQLError[];
+    extensions?: Record<string, unknown>;
+}
+interface WsSink<T> {
+    next(value: T): void;
+    error(error: unknown): void;
+    complete(): void;
+}
+/**
+ * Minimal interface matching the graphql-ws Client.
+ * Consumers pass a concrete instance via RealtimeConfig.client.
+ */
+export interface WsClient {
+    subscribe<TData = Record<string, unknown>>(payload: {
+        query: string;
+        variables?: Record<string, unknown>;
+    }, sink: WsSink<WsExecutionResult<TData>>): () => void;
+    dispose(): void;
+}
+/** The DML operation that triggered the subscription event */
+export type SubscriptionOperation = 'INSERT' | 'UPDATE' | 'DELETE';
+/** Connection state of the WebSocket */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/** Listener for connection state changes */
+export type ConnectionStateListener = (state: ConnectionState) => void;
+/** Function returned by subscribe() to cancel the subscription */
+export type Unsubscribe = () => void;
+/**
+ * A realtime subscription event delivered to the client.
+ *
+ * @typeParam T - The row type of the subscribed table
+ */
+export interface SubscriptionEvent<T> {
+    /** The DML operation that triggered this event */
+    operation: SubscriptionOperation;
+    /** The current row data (null for DELETE if row is no longer visible) */
+    data: T | null;
+    /** Previous field values (populated on UPDATE when available) */
+    previousValues?: Partial<T>;
+    /** Server-side timestamp of when the change occurred */
+    timestamp: string;
+}
+/**
+ * Options for creating a subscription.
+ *
+ * @typeParam T - The row type of the subscribed table
+ * @typeParam TFilter - The filter type for the table
+ */
+export interface SubscribeOptions<T, TFilter = Record<string, unknown>> {
+    /** Server-side filter to limit which events are delivered */
+    filter?: TFilter;
+    /** Called when a subscription event is received */
+    onEvent: (event: SubscriptionEvent<T>) => void;
+    /** Called when the subscription encounters an error */
+    onError?: (error: Error) => void;
+    /** Called when the subscription completes (server-initiated close) */
+    onComplete?: () => void;
+}
+/**
+ * Metadata about a subscription field, used internally to map
+ * table names to GraphQL subscription field names and types.
+ */
+export interface SubscriptionFieldMeta {
+    /** The GraphQL subscription field name (e.g., 'onContactChanged') */
+    fieldName: string;
+    /** The table name in the source schema (e.g., 'contact') */
+    tableName: string;
+    /** The data field name inside the subscription payload (e.g., 'contact') */
+    dataFieldName: string;
+}
+/**
+ * Configuration for the realtime (WebSocket) connection.
+ * Pass this as the `realtime` option in OrmClientConfig.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'graphql-ws';
+ *
+ * const client = createOrmClient({
+ *   endpoint: 'https://api.example.com/graphql',
+ *   realtime: {
+ *     client: createClient({ url: 'wss://api.example.com/graphql' }),
+ *   },
+ * });
+ * ```
+ */
+export interface RealtimeConfig {
+    /**
+     * A graphql-ws Client instance (or any object satisfying WsClient).
+     * The consumer creates this themselves, giving full control over
+     * connection options, auth, and transport.
+     *
+     * @example
+     * ```ts
+     * import { createClient } from 'graphql-ws';
+     * const wsClient = createClient({ url: 'wss://...' });
+     * ```
+     */
+    client: WsClient;
+}
+/**
+ * Manages a graphql-ws WebSocket client and multiplexes
+ * subscriptions over it. Created by OrmClient when `realtime`
+ * config is provided.
+ */
+export declare class RealtimeManager {
+    private wsClient;
+    private connectionState;
+    private stateListeners;
+    private activeSubscriptions;
+    constructor(config: RealtimeConfig);
+    /**
+     * Subscribe to a GraphQL subscription operation.
+     * Models call this with typed metadata and documents.
+     */
+    subscribe<T>(meta: SubscriptionFieldMeta, document: string, variables: Record<string, unknown>, options: {
+        onEvent: (event: SubscriptionEvent<T>) => void;
+        onError?: (error: Error) => void;
+        onComplete?: () => void;
+    }): Unsubscribe;
+    /** Register a listener for connection state changes */
+    onConnectionStateChange(listener: ConnectionStateListener): Unsubscribe;
+    /** Get current connection state */
+    getConnectionState(): ConnectionState;
+    /** Number of active subscriptions */
+    getActiveSubscriptionCount(): number;
+    /** Dispose the manager and close the WebSocket connection */
+    dispose(): void;
+    private setConnectionState;
+}
+export {};

package/esm/public/orm/realtime.js

@@ -0,0 +1,100 @@
+/**
+ * Realtime Manager - WebSocket subscription support
+ * @generated by @constructive-io/graphql-codegen
+ * DO NOT EDIT - changes will be overwritten
+ */
+// Minimal type shims so this module compiles without graphql-ws
+// installed.  Consumers supply a WsClient via RealtimeConfig;
+// the SDK itself never imports or requires graphql-ws.
+// ============================================================================
+// RealtimeManager
+// ============================================================================
+/**
+ * Manages a graphql-ws WebSocket client and multiplexes
+ * subscriptions over it. Created by OrmClient when `realtime`
+ * config is provided.
+ */
+export class RealtimeManager {
+    wsClient;
+    connectionState = 'disconnected';
+    stateListeners = new Set();
+    activeSubscriptions = 0;
+    constructor(config) {
+        this.wsClient = config.client;
+    }
+    /**
+     * Subscribe to a GraphQL subscription operation.
+     * Models call this with typed metadata and documents.
+     */
+    subscribe(meta, document, variables, options) {
+        this.activeSubscriptions++;
+        let disposed = false;
+        const cleanup = this.wsClient.subscribe({ query: document, variables }, {
+            next: (result) => {
+                if (disposed)
+                    return;
+                if (result.errors) {
+                    options.onError?.(new Error(result.errors.map((e) => e.message).join('; ')));
+                    return;
+                }
+                const payload = result.data?.[meta.fieldName];
+                if (!payload)
+                    return;
+                const event = {
+                    operation: payload.event ?? 'UPDATE',
+                    data: payload[meta.dataFieldName] ?? null,
+                    previousValues: payload.previousValues,
+                    timestamp: payload.timestamp ?? new Date().toISOString(),
+                };
+                options.onEvent(event);
+            },
+            error: (err) => {
+                if (disposed)
+                    return;
+                options.onError?.(err instanceof Error ? err : new Error(String(err)));
+            },
+            complete: () => {
+                if (disposed)
+                    return;
+                options.onComplete?.();
+            },
+        });
+        return () => {
+            if (disposed)
+                return;
+            disposed = true;
+            this.activeSubscriptions--;
+            cleanup();
+        };
+    }
+    /** Register a listener for connection state changes */
+    onConnectionStateChange(listener) {
+        this.stateListeners.add(listener);
+        return () => {
+            this.stateListeners.delete(listener);
+        };
+    }
+    /** Get current connection state */
+    getConnectionState() {
+        return this.connectionState;
+    }
+    /** Number of active subscriptions */
+    getActiveSubscriptionCount() {
+        return this.activeSubscriptions;
+    }
+    /** Dispose the manager and close the WebSocket connection */
+    dispose() {
+        this.wsClient.dispose();
+        this.stateListeners.clear();
+        this.activeSubscriptions = 0;
+        this.setConnectionState('disconnected');
+    }
+    setConnectionState(state) {
+        if (this.connectionState === state)
+            return;
+        this.connectionState = state;
+        for (const listener of this.stateListeners) {
+            listener(state);
+        }
+    }
+}