feat(spec): 73 个已发布 schema 补上参考页一直在丢弃的 export type 别名 (#4593)

.changeset/spec-documented-schema-type-alias-backfill.md

@@ -0,0 +1,70 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): 73 documented schemas gain the `export type` alias their reference page was silently dropping (#4593)
+
+Every generated page under `content/docs/references/` opens with a "TypeScript
+Usage" block that spells two imports — the schema const and the type alias. Since
+#4570 the generator resolves both names against the package's real export surface
+and **omits** anything that would not compile, so the docs have never advertised a
+dead import. The omission was countable rather than silent
+(`docs-import-surface.baseline.json`), and it was large: 136 documented JSON
+Schemas published a schema const with no type alias carrying the same name, so
+their pages showed the value import and no `import type` line at all. That is the
+line an AI metadata author copies.
+
+This backfills 73 of them. Each gets the ADR-0122 house shape — the bare name is
+the AUTHOR state:
+
+```ts
+export const FileValueSchema = lazySchema(() => z.looseObject({ ... }));
+export type FileValue = z.input<typeof FileValueSchema>;
+```
+
+Purely additive at the type level: 51 brand-new names, and 22 where the schema was
+already exported under its own bare name (`export const OWDModel = z.enum([...])`)
+so the alias merges with the existing const — `api-surface/` records those as
+`(type)` instead of `(const)`, which is the shape the package's 84 pre-existing
+const/type merges already have. No schema, `.describe()`, default or runtime
+behaviour moved; no consumer changed.
+
+By family: 22 closed enums and enum-like vocabularies (`ApproverType`,
+`AggregationFunction`, `DimensionType`, `SharingLevel`, `ReportType`,
+`ActionType`, `MetadataState`, …), 20 request/props shapes (three
+`DataEngine*Request`, `ElementNumberProps`, `ElementRecordPickerProps`,
+`RecordPathProps`, `MetadataValidateRequest`, `GetAnalyticsMetaRequest`, …), 9
+`data/` field-value shapes (`FileValue`, `LocationValue`, `InstantValue`,
+`AddressValue`, …), 7 `ui/view` configs (`KanbanConfig`, `GanttConfig`,
+`CalendarConfig`, `TreeConfig`, …), and 15 others across `system/`,
+`integration/`, `qa/`, `studio/`, `automation/`.
+
+Two entry points also re-export a name they were already publishing the schema
+for, so the type reaches the same subpath as its page: `ConnectorInstanceNoAuth`
+/ `Bearer` / `APIKey` / `BasicAuth` on `@objectstack/spec/integration`, and
+`PanelLocation` on `@objectstack/spec/studio`.
+
+The ratchet shrinks 136 → 63. What stays, and why — the remainder is not a
+backlog of identical work:
+
+- **17 already have the alias under a different name.** `Discovery` is published
+ as `DiscoveryResponse`, `SortDirectionEnum` as `SortDirection`, `Index` as
+ `ObjectIndex`. Declaring the docs-derived name as well would mint exactly the
+ permanent synonym ADR-0122 D3 forbids — a name an author can only pick wrongly
+ — so the honest fix is a rename or a doc-name change, not a second alias.
+- **40 are not isomorphic**: `z.input` differs from `z.infer`, so under
+ ADR-0122 the bare alias needs an `XParsed` sibling rather than a pin. Whether
+ those 40 `XParsed` names should be published is a separate call.
+- **5** sit in files under concurrent edit and were deferred rather than raced.
+- **1**, `system/ServiceStatus`, cannot take the name at all: `@objectstack/spec/api`
+ already exports a *different* `ServiceStatus` (the discovery health enum), so
+ the alias would create the cross-entry-point ambiguity
+ `check:dual-source-exports` exists to keep at zero. One of the two names is
+ wrong; picking which is a rename decision.
+
+Isomorphism was measured, not assumed: a probe asserting
+`Eq< z.input, z.infer >` over all 114 non-synonym candidates, compiled by tsc.
+The 73 that came back true are pinned in
+`packages/spec/src/type-alias-convention.pin.test.ts` (748 → 821), where tsc
+re-proves each one on every run and goes red the day a nested `.default()` gives
+one of them a second shape.

content/docs/references/ai/conversation.mdx

@@ -18,7 +18,7 @@ Enables context preservation, conversation history, and token optimization.
 
 ```typescript
 import { CodeContentSchema, ConversationAnalyticsSchema, ConversationContextSchema, ConversationMessageSchema, ConversationSessionSchema, ConversationSummarySchema, FileContentSchema, FunctionCallSchema, ImageContentSchema, MessageContentSchema, MessageContentTypeSchema, MessagePruningEventSchema, MessageRoleSchema, TextContentSchema, TokenBudgetConfigSchema, TokenBudgetStrategySchema, TokenUsageStatsSchema, ToolCallSchema } from '@objectstack/spec/ai';
-import type { ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FunctionCall, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai';
+import type { ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FileContent, FunctionCall, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TextContent, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai';
 
 // Validate data
 const result = CodeContentSchema.parse(data);

content/docs/references/api/analytics.mdx

@@ -18,7 +18,7 @@ Provides endpoints for executing analytical queries and discovering metadata.
 
 ```typescript
 import { AnalyticsEndpoint, AnalyticsMetadataResponseSchema, AnalyticsQueryRequestSchema, AnalyticsResultResponseSchema, AnalyticsSqlResponseSchema, GetAnalyticsMetaRequestSchema } from '@objectstack/spec/api';
-import type { AnalyticsEndpoint, AnalyticsMetadataResponse, AnalyticsQueryRequest, AnalyticsSqlResponse } from '@objectstack/spec/api';
+import type { AnalyticsEndpoint, AnalyticsMetadataResponse, AnalyticsQueryRequest, AnalyticsSqlResponse, GetAnalyticsMetaRequest } from '@objectstack/spec/api';
 
 // Validate data
 const result = AnalyticsEndpoint.parse(data);

content/docs/references/api/endpoint.mdx

@@ -16,7 +16,7 @@ Transform input/output data.
 
 ```typescript
 import { ApiEndpointSchema, ApiMappingSchema } from '@objectstack/spec/api';
-import type { ApiEndpoint } from '@objectstack/spec/api';
+import type { ApiEndpoint, ApiMapping } from '@objectstack/spec/api';
 
 // Validate data
 const result = ApiEndpointSchema.parse(data);

content/docs/references/api/metadata.mdx

@@ -36,7 +36,7 @@ the entire platform, including Hono, Next.js, and NestJS adapters.
 
 ```typescript
 import { AppDefinitionResponseSchema, ConceptListResponseSchema, MetadataBulkRegisterRequestSchema, MetadataBulkResponseSchema, MetadataBulkUnregisterRequestSchema, MetadataDeleteResponseSchema, MetadataDependenciesResponseSchema, MetadataDependentsResponseSchema, MetadataEffectiveResponseSchema, MetadataExistsResponseSchema, MetadataExportRequestSchema, MetadataExportResponseSchema, MetadataImportRequestSchema, MetadataImportResponseSchema, MetadataItemResponseSchema, MetadataListResponseSchema, MetadataNamesResponseSchema, MetadataOverlayResponseSchema, MetadataOverlaySaveRequestSchema, MetadataQueryRequestSchema, MetadataQueryResponseSchema, MetadataRegisterRequestSchema, MetadataTypeInfoResponseSchema, MetadataTypesResponseSchema, MetadataValidateRequestSchema, MetadataValidateResponseSchema, ObjectDefinitionResponseSchema } from '@objectstack/spec/api';
-import type { AppDefinitionResponse, ConceptListResponse, MetadataBulkRegisterRequest, MetadataBulkResponse, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataEffectiveResponse, MetadataExistsResponse, MetadataExportResponse, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataOverlayResponse, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypeInfoResponse, MetadataTypesResponse, MetadataValidateResponse, ObjectDefinitionResponse } from '@objectstack/spec/api';
+import type { AppDefinitionResponse, ConceptListResponse, MetadataBulkRegisterRequest, MetadataBulkResponse, MetadataBulkUnregisterRequest, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataEffectiveResponse, MetadataExistsResponse, MetadataExportResponse, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataOverlayResponse, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypeInfoResponse, MetadataTypesResponse, MetadataValidateRequest, MetadataValidateResponse, ObjectDefinitionResponse } from '@objectstack/spec/api';
 
 // Validate data
 const result = AppDefinitionResponseSchema.parse(data);

content/docs/references/api/realtime.mdx

@@ -13,7 +13,7 @@ description: Realtime protocol schemas
 
 ```typescript
 import { RealtimeConfigSchema, RealtimeEventSchema, RealtimeEventType, RealtimePresenceSchema, SubscriptionSchema, SubscriptionEventSchema, TransportProtocol } from '@objectstack/spec/api';
-import type { RealtimeConfig, RealtimeEvent, RealtimeEventType, RealtimePresence, Subscription, TransportProtocol } from '@objectstack/spec/api';
+import type { RealtimeConfig, RealtimeEvent, RealtimeEventType, RealtimePresence, Subscription, SubscriptionEvent, TransportProtocol } from '@objectstack/spec/api';
 
 // Validate data
 const result = RealtimeConfigSchema.parse(data);

content/docs/references/automation/approval.mdx

@@ -13,7 +13,7 @@ description: Approval protocol schemas
 
 ```typescript
 import { ApprovalDecision, ApprovalEscalationSchema, ApprovalNodeApproverSchema, ApprovalNodeConfigSchema, ApproverType, DecisionOutputDefSchema } from '@objectstack/spec/automation';
-import type { ApprovalDecision, ApprovalEscalation, ApprovalNodeApprover, ApprovalNodeConfig, DecisionOutputDef } from '@objectstack/spec/automation';
+import type { ApprovalDecision, ApprovalEscalation, ApprovalNodeApprover, ApprovalNodeConfig, ApproverType, DecisionOutputDef } from '@objectstack/spec/automation';
 
 // Validate data
 const result = ApprovalDecision.parse(data);

content/docs/references/automation/flow.mdx

@@ -25,7 +25,7 @@ no longer constrains authored flows — plugins extend the vocabulary.
 
 ```typescript
 import { FlowSchema, FlowEdgeSchema, FlowNodeSchema, FlowNodeAction, FlowVariableSchema, FlowVersionHistorySchema } from '@objectstack/spec/automation';
-import type { Flow, FlowEdge, FlowNode, FlowVersionHistory } from '@objectstack/spec/automation';
+import type { Flow, FlowEdge, FlowNode, FlowNodeAction, FlowVersionHistory } from '@objectstack/spec/automation';
 
 // Validate data
 const result = FlowSchema.parse(data);

content/docs/references/automation/state-machine.mdx

@@ -69,7 +69,7 @@ is no openness here to preserve, only a silence to end.
 
 ```typescript
 import { ActionRefSchema, GuardRefSchema, StateMachineSchema, StateNodeSchema, TransitionSchema } from '@objectstack/spec/automation';
-import type { ActionRef, Transition } from '@objectstack/spec/automation';
+import type { ActionRef, GuardRef, StateNode, Transition } from '@objectstack/spec/automation';
 
 // Validate data
 const result = ActionRefSchema.parse(data);

content/docs/references/data/analytics.mdx

@@ -21,7 +21,7 @@ This layer decouples the "Physical Data" (Tables/Columns) from the
 
 ```typescript
 import { AggregationMetricType, AnalyticsQuerySchema, CubeSchema, CubeJoinSchema, DimensionSchema, DimensionType, MetricSchema, TimeUpdateInterval } from '@objectstack/spec/data';
-import type { AnalyticsQuery, Cube, CubeJoin, Dimension, Metric } from '@objectstack/spec/data';
+import type { AggregationMetricType, AnalyticsQuery, Cube, CubeJoin, Dimension, DimensionType, Metric, TimeUpdateInterval } from '@objectstack/spec/data';
 
 // Validate data
 const result = AggregationMetricType.parse(data);

content/docs/references/data/context-tokens.mdx

@@ -84,7 +84,7 @@ selector state.
 
 ```typescript
 import { ContextTokenSchema, ContextTokenPlaceholderSchema } from '@objectstack/spec/data';
-import type { ContextToken } from '@objectstack/spec/data';
+import type { ContextToken, ContextTokenPlaceholder } from '@objectstack/spec/data';
 
 // Validate data
 const result = ContextTokenSchema.parse(data);

content/docs/references/data/data-engine.mdx

@@ -22,7 +22,7 @@ The Data Engine acts as the "Driver" layer in the Hexagonal Architecture.
 
 ```typescript
 import { BaseEngineOptionsSchema, DataEngineAggregateOptionsSchema, DataEngineAggregateRequestSchema, DataEngineCountOptionsSchema, DataEngineCountRequestSchema, DataEngineDeleteOptionsSchema, DataEngineDeleteRequestSchema, DataEngineExecuteRequestSchema, DataEngineFilterSchema, DataEngineFindOneRequestSchema, DataEngineFindRequestSchema, DataEngineInsertOptionsSchema, DataEngineInsertRequestSchema, DataEngineQueryOptionsSchema, DataEngineRequestSchema, DataEngineSortSchema, DataEngineUpdateOptionsSchema, DataEngineUpdateRequestSchema, DataEngineVectorFindRequestSchema, DroppedFieldsEventSchema, EngineAggregateOptionsSchema, EngineCountOptionsSchema, EngineDeleteOptionsSchema, EngineQueryOptionsSchema, EngineUpdateOptionsSchema } from '@objectstack/spec/data';
-import type { BaseEngineOptions, DataEngineAggregateOptions, DataEngineCountOptions, DataEngineDeleteOptions, DataEngineFilter, DataEngineInsertOptions, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DroppedFieldsEvent, EngineAggregateOptions, EngineCountOptions, EngineDeleteOptions, EngineQueryOptions, EngineUpdateOptions } from '@objectstack/spec/data';
+import type { BaseEngineOptions, DataEngineAggregateOptions, DataEngineCountOptions, DataEngineDeleteOptions, DataEngineExecuteRequest, DataEngineFilter, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineVectorFindRequest, DroppedFieldsEvent, EngineAggregateOptions, EngineCountOptions, EngineDeleteOptions, EngineQueryOptions, EngineUpdateOptions } from '@objectstack/spec/data';
 
 // Validate data
 const result = BaseEngineOptionsSchema.parse(data);

content/docs/references/data/datasource.mdx

@@ -16,7 +16,7 @@ Can be a built-in driver or a plugin-contributed driver (e.g., "com.vendor.snowf
 
 ```typescript
 import { DatasourceSchema, DriverDefinitionSchema, DriverType, ExternalDatasourceSettingsSchema, SchemaModeSchema } from '@objectstack/spec/data';
-import type { Datasource, DriverDefinition, ExternalDatasourceSettings, SchemaMode } from '@objectstack/spec/data';
+import type { Datasource, DriverDefinition, DriverType, ExternalDatasourceSettings, SchemaMode } from '@objectstack/spec/data';
 
 // Validate data
 const result = DatasourceSchema.parse(data);

content/docs/references/data/date-macros.mdx

@@ -84,7 +84,7 @@ inside any single UI implementation.
 
 ```typescript
 import { DateMacroPlaceholderSchema, DateMacroTokenSchema } from '@objectstack/spec/data';
-import type { DateMacroToken } from '@objectstack/spec/data';
+import type { DateMacroPlaceholder, DateMacroToken } from '@objectstack/spec/data';
 
 // Validate data
 const result = DateMacroPlaceholderSchema.parse(data);

content/docs/references/data/driver-common.mdx

@@ -28,7 +28,7 @@ contract to look supported.
 
 ```typescript
 import { DriverSslToggleSchema, SqlAutoMigrateSchema } from '@objectstack/spec/data';
-import type { SqlAutoMigrate } from '@objectstack/spec/data';
+import type { DriverSslToggle, SqlAutoMigrate } from '@objectstack/spec/data';
 
 // Validate data
 const result = DriverSslToggleSchema.parse(data);

content/docs/references/data/field-value.mdx

@@ -41,6 +41,7 @@ this contract has (ADR-0104 performance budget).
 
 ```typescript
 import { AddressValueSchema, CalendarDateValueSchema, ClockTimeValueSchema, FileLikeValueSchema, FileReferenceIdValueSchema, FileValueSchema, InstantValueSchema, LocationValueSchema, ReferenceIdValueSchema } from '@objectstack/spec/data';
+import type { AddressValue, CalendarDateValue, ClockTimeValue, FileLikeValue, FileReferenceIdValue, FileValue, InstantValue, LocationValue, ReferenceIdValue } from '@objectstack/spec/data';
 
 // Validate data
 const result = AddressValueSchema.parse(data);

content/docs/references/data/mapping.mdx

@@ -13,7 +13,7 @@ description: Mapping protocol schemas
 
 ```typescript
 import { ImportFieldMappingSchema, MappingSchema, TransformType } from '@objectstack/spec/data';
-import type { ImportFieldMapping, Mapping } from '@objectstack/spec/data';
+import type { ImportFieldMapping, Mapping, TransformType } from '@objectstack/spec/data';
 
 // Validate data
 const result = ImportFieldMappingSchema.parse(data);

content/docs/references/data/query.mdx

@@ -17,7 +17,7 @@ REJECTED (#4721); spell the direction `order`, never `direction`.
 
 ```typescript
 import { AggregationFunction, AggregationNodeSchema, DateGranularity, FieldNodeSchema, FullTextSearchSchema, GroupByNodeSchema, QuerySchema, SortNodeSchema } from '@objectstack/spec/data';
-import type { AggregationNode, FieldNode, FullTextSearch, GroupByNode, SortNode } from '@objectstack/spec/data';
+import type { AggregationFunction, AggregationNode, FieldNode, FullTextSearch, GroupByNode, SortNode } from '@objectstack/spec/data';
 
 // Validate data
 const result = AggregationFunction.parse(data);

content/docs/references/integration/connector.mdx

@@ -128,7 +128,7 @@ an exception for itself.)
 
 ```typescript
 import { CircuitBreakerConfigSchema, ConnectorSchema, ConnectorActionSchema, ConnectorActionEffectSchema, ConnectorConflictResolutionSchema, ConnectorErrorCategorySchema, ConnectorFieldMappingSchema, ConnectorHealthSchema, ConnectorInstanceAPIKeyAuthSchema, ConnectorInstanceAuthSchema, ConnectorInstanceBasicAuthSchema, ConnectorInstanceBearerAuthSchema, ConnectorInstanceNoAuthSchema, ConnectorRetryStrategySchema, ConnectorStatusSchema, ConnectorTriggerSchema, ConnectorTypeSchema, DataSyncConfigSchema, DeclarativeConnectorEntrySchema, ErrorMappingConfigSchema, ErrorMappingRuleSchema, HealthCheckConfigSchema, RetryConfigSchema, SyncStrategySchema, WebhookConfigSchema, WebhookEventSchema, WebhookSignatureAlgorithmSchema } from '@objectstack/spec/integration';
-import type { CircuitBreakerConfig, Connector, ConnectorActionEffect, ConnectorConflictResolution, ConnectorErrorCategory, ConnectorFieldMapping, ConnectorHealth, ConnectorInstanceAuth, ConnectorRetryStrategy, ConnectorStatus, ConnectorType, DataSyncConfig, DeclarativeConnectorEntry, ErrorMappingConfig, ErrorMappingRule, HealthCheckConfig, RetryConfig, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration';
+import type { CircuitBreakerConfig, Connector, ConnectorAction, ConnectorActionEffect, ConnectorConflictResolution, ConnectorErrorCategory, ConnectorFieldMapping, ConnectorHealth, ConnectorInstanceAPIKeyAuth, ConnectorInstanceAuth, ConnectorInstanceBasicAuth, ConnectorInstanceBearerAuth, ConnectorInstanceNoAuth, ConnectorRetryStrategy, ConnectorStatus, ConnectorTrigger, ConnectorType, DataSyncConfig, DeclarativeConnectorEntry, ErrorMappingConfig, ErrorMappingRule, HealthCheckConfig, RetryConfig, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration';
 
 // Validate data
 const result = CircuitBreakerConfigSchema.parse(data);

content/docs/references/qa/testing.mdx

@@ -13,7 +13,7 @@ description: Testing protocol schemas
 
 ```typescript
 import { TestActionSchema, TestActionTypeSchema, TestAssertionSchema, TestAssertionTypeSchema, TestContextSchema, TestScenarioSchema, TestStepSchema, TestSuiteSchema } from '@objectstack/spec/qa';
-import type { TestAction, TestAssertion, TestScenario, TestStep, TestSuite } from '@objectstack/spec/qa';
+import type { TestAction, TestActionType, TestAssertion, TestAssertionType, TestContext, TestScenario, TestStep, TestSuite } from '@objectstack/spec/qa';
 
 // Validate data
 const result = TestActionSchema.parse(data);

content/docs/references/security/sharing.mdx

@@ -16,7 +16,7 @@ The baseline security posture for an object.
 
 ```typescript
 import { CriteriaSharingRuleSchema, OWDModel, ShareRecipientType, SharingLevel, SharingRuleSchema, SharingRuleType } from '@objectstack/spec/security';
-import type { CriteriaSharingRule, SharingRule } from '@objectstack/spec/security';
+import type { CriteriaSharingRule, OWDModel, ShareRecipientType, SharingLevel, SharingRule, SharingRuleType } from '@objectstack/spec/security';
 
 // Validate data
 const result = CriteriaSharingRuleSchema.parse(data);