feat(spec): defineX factories + XInput aliases for the 16 remaining writable domains (#2035)

Adds one type-safe authoring entry per writable domain — defineDatasource,
defineConnector, definePolicy, defineSharingRule, defineRole, definePermissionSet,
defineEmailTemplateDefinition, defineReport, defineWebhook, defineObjectExtension,
defineCube, defineMapping, defineTheme, defineTranslationBundle, definePage,
defineAction — mirroring the 19 existing factories (XSchema.parse(z.input)).

Each factory is a *value* export: a broken import hard-errors instead of silently
degrading to `any` (the #2023 failure mode), and authoring errors surface at
.parse() time with field-level messages. Also backfills the six missing input
aliases: PolicyInput, CubeInput, MappingInput, ThemeInput, TranslationBundleInput,
PageInput. Purely additive — no existing exports change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.changeset/spec-define-x-factories.md

@@ -0,0 +1,22 @@
+---
+"@objectstack/spec": minor
+---
+
+spec: add `defineX` factories for the remaining 16 writable domains and the 6
+missing `XInput` aliases — one consistent, type-safe authoring entry per domain
+(#2035).
+
+New factories: `defineDatasource`, `defineConnector`, `definePolicy`,
+`defineSharingRule`, `defineRole`, `definePermissionSet`,
+`defineEmailTemplateDefinition`, `defineReport`, `defineWebhook`,
+`defineObjectExtension`, `defineCube`, `defineMapping`, `defineTheme`,
+`defineTranslationBundle`, `definePage`, `defineAction`. Each mirrors the 19
+existing factories (`XSchema.parse(z.input<…>)`): input-shape ergonomics +
+authoring-time validation. Because a factory is a *value* import, a broken
+import hard-errors instead of silently degrading to `any` (the #2023 failure
+mode), and errors surface at `.parse()` time with field-level messages.
+
+Also adds the previously-missing input aliases `PolicyInput`, `CubeInput`,
+`MappingInput`, `ThemeInput`, `TranslationBundleInput`, `PageInput`.
+
+Purely additive: no existing exports change.

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

@@ -144,3 +144,12 @@ export type Webhook = z.infer<typeof WebhookSchema>;
 /** Authoring input for {@link Webhook} — defaulted fields are optional. */
 export type WebhookInput = z.input<typeof WebhookSchema>;
 export type WebhookReceiver = z.infer<typeof WebhookReceiverSchema>;
+
+/**
+ * Type-safe factory for an outbound webhook. Validates at authoring time via
+ * `.parse()` and accepts input-shape config (optional defaults, CEL
+ * shorthand) — preferred over a bare `: Webhook` literal.
+ */
+export function defineWebhook(config: z.input<typeof WebhookSchema>): Webhook {
+  return WebhookSchema.parse(config);
+}

packages/spec/src/data/analytics.zod.ts

@@ -174,4 +174,15 @@ export type Metric = z.infer<typeof MetricSchema>;
 export type Dimension = z.infer<typeof DimensionSchema>;
 export type CubeJoin = z.infer<typeof CubeJoinSchema>;
 export type Cube = z.infer<typeof CubeSchema>;
+/** Authoring input for {@link Cube} — defaulted fields are optional. */
+export type CubeInput = z.input<typeof CubeSchema>;
+
+/**
+ * Type-safe factory for an analytics semantic-layer cube. Validates at authoring time via
+ * `.parse()` and accepts input-shape config (optional defaults, CEL
+ * shorthand) — preferred over a bare `: Cube` literal.
+ */
+export function defineCube(config: z.input<typeof CubeSchema>): Cube {
+  return CubeSchema.parse(config);
+}
 export type AnalyticsQuery = z.infer<typeof AnalyticsQuerySchema>;

packages/spec/src/data/datasource.zod.ts

@@ -260,3 +260,12 @@ export type Datasource = z.infer<typeof DatasourceSchema>;
 /** Authoring input for {@link Datasource} — defaulted fields are optional. */
 export type DatasourceInput = z.input<typeof DatasourceSchema>;
 export type DatasourceCapabilitiesType = z.infer<typeof DatasourceCapabilities>;
+
+/**
+ * Type-safe factory for an external data connection (datasource). Validates at authoring time via
+ * `.parse()` and accepts input-shape config (optional defaults, CEL
+ * shorthand) — preferred over a bare `: Datasource` literal.
+ */
+export function defineDatasource(config: z.input<typeof DatasourceSchema>): Datasource {
+  return DatasourceSchema.parse(config);
+}

packages/spec/src/data/mapping.zod.ts

@@ -92,4 +92,15 @@ export const MappingSchema = lazySchema(() => z.object({
 }));
 
 export type Mapping = z.infer<typeof MappingSchema>;
+/** Authoring input for {@link Mapping} — defaulted fields are optional. */
+export type MappingInput = z.input<typeof MappingSchema>;
+
+/**
+ * Type-safe factory for a data import/export mapping. Validates at authoring time via
+ * `.parse()` and accepts input-shape config (optional defaults, CEL
+ * shorthand) — preferred over a bare `: Mapping` literal.
+ */
+export function defineMapping(config: z.input<typeof MappingSchema>): Mapping {
+  return MappingSchema.parse(config);
+}
 export type FieldMapping = z.infer<typeof FieldMappingSchema>;

packages/spec/src/data/object.zod.ts

@@ -1011,3 +1011,12 @@ export const ObjectExtensionSchema = lazySchema(() => z.object({
 export type ObjectExtension = z.infer<typeof ObjectExtensionSchema>;
 /** Authoring input for {@link ObjectExtension} — defaulted fields are optional. */
 export type ObjectExtensionInput = z.input<typeof ObjectExtensionSchema>;
+
+/**
+ * Type-safe factory for an extension to an object owned by another package. Validates at authoring time via
+ * `.parse()` and accepts input-shape config (optional defaults, CEL
+ * shorthand) — preferred over a bare `: ObjectExtension` literal.
+ */
+export function defineObjectExtension(config: z.input<typeof ObjectExtensionSchema>): ObjectExtension {
+  return ObjectExtensionSchema.parse(config);
+}

packages/spec/src/identity/role.zod.ts

@@ -45,3 +45,12 @@ export const RoleSchema = lazySchema(() => z.object({
 export type Role = z.infer<typeof RoleSchema>;
 /** Authoring input for {@link Role} — defaulted fields are optional. */
 export type RoleInput = z.input<typeof RoleSchema>;
+
+/**
+ * Type-safe factory for a role in the role hierarchy. Validates at authoring time via
+ * `.parse()` and accepts input-shape config (optional defaults, CEL
+ * shorthand) — preferred over a bare `: Role` literal.
+ */
+export function defineRole(config: z.input<typeof RoleSchema>): Role {
+  return RoleSchema.parse(config);
+}

packages/spec/src/index.ts

@@ -80,6 +80,27 @@ export { defineBook } from './system/book.zod';
 export { defineAgent } from './ai/agent.zod';
 export { defineTool } from './ai/tool.zod';
 export { defineSkill } from './ai/skill.zod';
+
+// DX factories for the remaining authoring domains (issue #2035) — one type-safe
+// entry per writable domain, mirroring the 19 factories above. `defineX` is a
+// *value* import: a broken import hard-errors instead of silently degrading to
+// `any` (the #2023 failure mode). Input-shape config + runtime `.parse()`.
+export { defineDatasource } from './data/datasource.zod';
+export { defineConnector } from './integration/connector.zod';
+export { definePolicy } from './security/policy.zod';
+export { defineSharingRule } from './security/sharing.zod';
+export { defineRole } from './identity/role.zod';
+export { definePermissionSet } from './security/permission.zod';
+export { defineEmailTemplateDefinition } from './system/email-template.zod';
+export { defineReport } from './ui/report.zod';
+export { defineWebhook } from './automation/webhook.zod';
+export { defineObjectExtension } from './data/object.zod';
+export { defineCube } from './data/analytics.zod';
+export { defineMapping } from './data/mapping.zod';
+export { defineTheme } from './ui/theme.zod';
+export { defineTranslationBundle } from './system/translation.zod';
+export { definePage } from './ui/page.zod';
+export { defineAction } from './ui/action.zod';
 export type { Agent } from './ai/agent.zod';
 export type { Tool } from './ai/tool.zod';
 export type { Skill } from './ai/skill.zod';

packages/spec/src/integration/connector.zod.ts

@@ -630,3 +630,12 @@ export const ConnectorSchema = lazySchema(() => z.object({
 export type Connector = z.infer<typeof ConnectorSchema>;
 /** Authoring input for {@link Connector} — defaulted fields are optional. */
 export type ConnectorInput = z.input<typeof ConnectorSchema>;
+
+/**
+ * Type-safe factory for an external-system connector. Validates at authoring time via
+ * `.parse()` and accepts input-shape config (optional defaults, CEL
+ * shorthand) — preferred over a bare `: Connector` literal.
+ */
+export function defineConnector(config: z.input<typeof ConnectorSchema>): Connector {
+  return ConnectorSchema.parse(config);
+}

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

@@ -196,3 +196,12 @@ export type PermissionSet = z.infer<typeof PermissionSetSchema>;
 export type PermissionSetInput = z.input<typeof PermissionSetSchema>;
 export type ObjectPermission = z.infer<typeof ObjectPermissionSchema>;
 export type FieldPermission = z.infer<typeof FieldPermissionSchema>;
+
+/**
+ * Type-safe factory for a permission set / profile. Validates at authoring time via
+ * `.parse()` and accepts input-shape config (optional defaults, CEL
+ * shorthand) — preferred over a bare `: PermissionSet` literal.
+ */
+export function definePermissionSet(config: z.input<typeof PermissionSetSchema>): PermissionSet {
+  return PermissionSetSchema.parse(config);
+}