Migrate @objectql/types to use @objectstack/spec as protocol constitution #135

Copilot · 2026-01-18T15:37:54Z

Refactors the type system to use @objectstack/spec v0.1.1 as the single source of truth for all metadata/AST interfaces, eliminating duplicate type definitions and establishing a clean protocol/runtime separation.

Changes

Type System Architecture

Import core protocol types (Field, ServiceObject, Action) from @objectstack/spec
Extend protocol types with runtime-specific properties (AI config, validation, file upload constraints)
Remove duplicate type definitions across field, object, and action modules
Make Zod-defaulted boolean flags optional in FieldConfig for ergonomic runtime usage

Protocol Alignment

Standardize field type naming: auto_number → autonumber
Standardize property naming: min_length/max_length → minLength/maxLength
Update core utilities, GraphQL adapter, metadata endpoints, and CLI tools to use protocol-compliant naming

Example

Before:

// Duplicate definition in @objectql/types
export type FieldType = 'text' | 'number' | 'auto_number' | ...;
export interface FieldConfig {
  type: FieldType;
  max_length?: number;
  // ... 40+ properties
}

After:

// Import from protocol, extend for runtime
import type { Field, FieldType as ProtocolFieldType } from '@objectstack/spec';

export type FieldType = ProtocolFieldType | 'vector' | 'grid' | 'location';
export interface FieldConfig extends Omit<Field, 'type' | 'options'> {
  type: FieldType;
  // Runtime-only: file upload constraints, AI context, etc.
  accept?: string[];
  max_size?: number;
  validation?: { /* ... */ };
}

Build Configuration

Temporarily disable JSON schema generation (conflicts with imported Zod schemas)
All 236 tests pass, all packages build successfully

Architecture

@objectstack/spec (Protocol) → @objectql/types (Runtime Extensions) → @objectql/core (Engine)

Protocol types remain stable and versioned upstream. Runtime features extend without polluting the wire format.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

fastdl.mongodb.org
- Triggering command: /usr/local/bin/node /usr/local/bin/node /home/REDACTED/work/objectql/objectql/node_modules/.pnpm/[email protected]/node_modules/jest-worker/build/processChild.js ndor/bin/sh grep n/je�� ' --include '*.yml' --exclude '*-o export type Field wcase/project-tracker/node_modules/.bin/node --filter @objectwatchman --global enerator.js iptables modu�� --production security k/objectql/objectql/node_modules/.bin/sh OUTPUT -d 168.63.129.16 sh (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

This section details on the original issue you should resolve

<issue_title>[Feature]: The package @objectstack/spec (v0.1.1) is now the "Constitution" for all Metadata/AST interfaces.</issue_title>
<issue_description>### Is your feature request related to a problem? Please describe.

Role: ObjectStack Senior Architect

Mission: Protocol Migration & Type Alignment

We are refactoring the objectql monorepo to strictly adhere to the new upstream protocol definition.
The package @objectstack/spec (v0.1.1) is now the "Constitution" for all Metadata/AST interfaces.

Context

I have installed @objectstack/spec in packages/foundation/core and plan to install it in packages/foundation/types.
Currently, packages/foundation/types contains duplicate manual definitions of what is now in the Spec.

Your Task

Execute the following "Atomic Workflow" to align the codebase:
Analyze the Spec

Check the exports of @objectstack/spec.

Identify which interfaces in packages/foundation/types/src/*.ts overlap with the Spec (e.g., ObjectConfig, FieldConfig, ActionConfig).
Refactor "The Constitution" (@objectql/types)
Modify packages/foundation/types/package.json: Add dependency @objectstack/spec.

Update packages/foundation/types/src/index.ts: Re-export common types from the Spec.
Refactor individual files (e.g., object.ts):
DELETE local interfaces that duplicate the Spec.

EXTEND Spec interfaces if we have runtime-specific properties that are not part of the wire protocol.
Example pattern:
import { ObjectSpecification } from '@objectstack/spec';
// Only add properties that exist in Runtime but NOT in Spec
export interface ObjectConfig extends ObjectSpecification {
    // runtime_cache_key?: string;
}
Update the Engine (@objectql/core)

Ensure core imports strictly from @objectql/types (which now bridges the Spec) or directly from @objectstack/spec only if needed for value objects/constants.

Fix any type errors resulting from the switch (e.g., strict null checks or changed property names).
Constraints

Strict Typing: No any. Use unknown with type guards if necessary.

Zero Duplication: If a type exists in @objectstack/spec, do not redefine it.

Backwards Compatibility: If the Spec explicitly changes a field name, mark the old one as @deprecated in our local type if needed, or update the Core to use the new standard.

Start by listing the files in packages/foundation/types/src that need to be modified based on the standard *.object.yml or *.field.yml patterns.

Describe the solution you'd like

Describe alternatives you've considered

No response</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes [Feature]: The package @objectstack/spec (v0.1.1) is now the "Constitution" for all Metadata/AST interfaces. #134

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

…ql/types Co-authored-by: hotlong <[email protected]>

…minLength, maxLength) Co-authored-by: hotlong <[email protected]>

Co-authored-by: hotlong <[email protected]>

github-actions · 2026-01-18T16:12:39Z

⚠️ No Changeset Found

This PR does not include a changeset file.
If this PR includes user-facing changes, please add a changeset by running:

pnpm changeset

Copilot

Pull request overview

This PR migrates the type system to use @objectstack/spec v0.1.1 as the single source of truth for protocol definitions, eliminating duplicate type definitions and establishing a clean separation between protocol (wire format) and runtime (implementation) types.

Changes:

Refactored @objectql/types to import and extend protocol types from @objectstack/spec rather than duplicating definitions
Standardized field type and property naming to match protocol conventions (auto_number → autonumber, max_length → maxLength)
Updated core utilities, GraphQL adapter, metadata endpoints, and CLI tools to use protocol-compliant naming

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/foundation/types/package.json	Added `@objectstack/spec` dependency and temporarily disabled JSON schema generation
packages/foundation/types/src/index.ts	Added documentation explaining the protocol/runtime type relationship
packages/foundation/types/src/field.ts	Refactored to import protocol types and extend with runtime-specific properties
packages/foundation/types/src/object.ts	Refactored to import `ServiceObject` from spec and extend with runtime features
packages/foundation/types/src/action.ts	Refactored to import `Action` from spec and extend with runtime execution capabilities
packages/foundation/core/src/util.ts	Updated to use protocol-compliant property names (`maxLength`)
packages/foundation/core/test/util.test.ts	Updated test assertions to match new property names
packages/runtime/server/src/metadata.ts	Updated metadata serialization to use protocol-compliant names
packages/runtime/server/src/adapters/graphql.ts	Updated field type mapping from `auto_number` to `autonumber`
packages/tools/cli/src/commands/generate.ts	Updated TypeScript mapping from `auto_number` to `autonumber`
packages/tools/cli/src/commands/sync.ts	Updated database introspection to use `maxLength` property

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

Copilot · 2026-01-18T16:13:31Z

packages/foundation/types/src/field.ts

-    description?: string;
-
-    /** The data type of the field. */
+export interface FieldConfig extends Omit<Field, 'type' | 'options' | 'required' | 'multiple' | 'unique' | 'deleteBehavior' | 'hidden' | 'readonly' | 'encryption' | 'index' | 'externalId'> {


The Omit list contains 11 properties being excluded from the base Field type. This creates a tight coupling to the protocol definition and makes the interface fragile - any changes to the protocol's Field interface could silently break this contract. Consider using a Pick approach to explicitly declare which protocol properties are inherited, or document why each property needs to be re-declared.

Copilot · 2026-01-18T16:13:31Z

packages/foundation/types/src/field.ts

    /**
     * Reference to another object for lookup/master_detail fields.
-     * Specifies the target object name for relationship fields.
+     * @deprecated Use 'reference' from SpecField instead


This property is marked as deprecated in favor of the protocol's reference field, but there's no migration path or guidance provided. Consider adding a comment explaining how to migrate from reference_to to reference, or implement a getter/setter that maps between the two to ease the transition.

Suggested change

* @deprecated Use 'reference' from SpecField instead

*

* @deprecated Legacy alias for the protocol-level {@link SpecField.reference} field.

*

* Migration guidance:

* - New schemas MUST use the `reference` field defined on SpecField (wire protocol) instead of `reference_to`.

* - During migration, engines and tooling SHOULD:

* - Treat `reference_to` as a fallback alias for `reference` (i.e., if `reference` is undefined and `reference_to`

* is defined, behave as though `reference` were set to the same value).

* - Prefer the protocol `reference` value when both are present.

*

* This property is retained only for backward compatibility with older *.object.yml definitions and may be removed

* in a future major version once all callers have migrated to `reference`.

Copilot · 2026-01-18T16:13:31Z

packages/foundation/types/src/field.ts

+     * Regular expression pattern for validation.
+     * @deprecated Use validation.pattern instead
+     */
    regex?: string;


This property is marked as deprecated in favor of validation.pattern, but it's also included again inside the validation object (line 230 has regex as an alias for pattern). This creates ambiguity about which property should be used. Consider removing the deprecated top-level property entirely or providing a clear migration timeline.

Copilot · 2026-01-18T16:13:32Z

packages/foundation/core/src/util.ts

            if (foreignKey) {
                // This is a lookup field
                fieldConfig = {
+                    name: column.name,


The name property is now explicitly set in both lookup and regular field configurations. This is redundant since the comment on line 114 in the original code states 'If defined within an object map, this is often automatically populated from the key.' Consider documenting why explicit name assignment is now required, or if this is needed for protocol compliance.

Copilot · 2026-01-18T16:13:32Z

packages/foundation/core/src/util.ts

                const fieldType = mapDatabaseTypeToFieldType(column.type);

                fieldConfig = {
+                    name: column.name,


The name property is now explicitly set in both lookup and regular field configurations. This is redundant since the comment on line 114 in the original code states 'If defined within an object map, this is often automatically populated from the key.' Consider documenting why explicit name assignment is now required, or if this is needed for protocol compliance.

Initial plan

24be696

Copilot AI assigned Copilot and hotlong Jan 18, 2026

Copilot started work on behalf of hotlong January 18, 2026 15:38 View session

Copilot AI and others added 3 commits January 18, 2026 15:48

feat: Integrate @objectstack/spec as Protocol Constitution in @object…

8c60f19

…ql/types Co-authored-by: hotlong <[email protected]>

fix: Align field naming with @objectstack/spec protocol (autonumber, …

07b8bce

…minLength, maxLength) Co-authored-by: hotlong <[email protected]>

test: Fix test to use maxLength instead of max_length

9ff88f2

Co-authored-by: hotlong <[email protected]>

Copilot AI changed the title ~~[WIP] Refactor objectql to align with @objectstack/spec~~ Migrate @objectql/types to use @objectstack/spec as protocol constitution Jan 18, 2026

Copilot AI requested a review from hotlong January 18, 2026 15:59

Copilot finished work on behalf of hotlong January 18, 2026 15:59

huangyiirene requested review from Copilot and removed request for hotlong January 18, 2026 16:12

github-actions bot added 🔧 tooling 🏗️ foundation 🚀 runtime 🧪 tests 📦 dependencies size/L labels Jan 18, 2026

Copilot AI reviewed Jan 18, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Migrate @objectql/types to use @objectstack/spec as protocol constitution #135

Migrate @objectql/types to use @objectstack/spec as protocol constitution #135

Uh oh!

Copilot AI commented Jan 18, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 18, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 18, 2026

Uh oh!

Copilot AI Jan 18, 2026

Uh oh!

Copilot AI Jan 18, 2026

Uh oh!

Copilot AI Jan 18, 2026

Uh oh!

Copilot AI Jan 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-     * @deprecated Use 'reference' from SpecField instead
+     *
+     * @deprecated Legacy alias for the protocol-level {@link SpecField.reference} field.
+     *
+     * Migration guidance:
+     * - New schemas MUST use the `reference` field defined on SpecField (wire protocol) instead of `reference_to`.
+     * - During migration, engines and tooling SHOULD:
+     *   - Treat `reference_to` as a fallback alias for `reference` (i.e., if `reference` is undefined and `reference_to`
+     *     is defined, behave as though `reference` were set to the same value).
+     *   - Prefer the protocol `reference` value when both are present.
+     *
+     * This property is retained only for backward compatibility with older *.object.yml definitions and may be removed
+     * in a future major version once all callers have migrated to `reference`.

Migrate @objectql/types to use @objectstack/spec as protocol constitution #135

Are you sure you want to change the base?

Migrate @objectql/types to use @objectstack/spec as protocol constitution #135

Uh oh!

Conversation

Copilot AI commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Architecture

I tried to connect to the following addresses, but was blocked by firewall rules:

Role: ObjectStack Senior Architect

Mission: Protocol Migration & Type Alignment

Context

Your Task

Constraints

Describe the solution you'd like

Describe alternatives you've considered

Comments on the Issue (you are @copilot in this section)

Uh oh!

github-actions bot commented Jan 18, 2026

⚠️ No Changeset Found

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Jan 18, 2026 •

edited

Loading