Assessment: Airtable Interface Designer Pattern for ObjectUI

[hotlong]

1. Understanding the Airtable Pattern

From the screenshots, Airtable's Interface Designer implements a Design → Stage → Publish workflow:

— List View Interface: A customer management list page with a left sidebar navigation, configurable view (Sort, Filter, Group), and a right-hand property panel controlling Page type, Data binding, Appearance, and User Actions.

— Dashboard Interface: A performance dashboard with KPI cards, charts (Line, Bar, Pie), and a right-hand property panel for chart configuration (Source, Axes, Appearance).

Key observations from both screenshots:

Feature	Detail
Publish Status	"No changes · Last published Feb 21, 2026" / "Interface has unpublished changes · Last published Feb 18, 2026"
Workflow	Design (edit mode, blue dashed borders) → Stage (preview as "Yourself") → Publish (red button)
Navigation	Hierarchical sidebar: App → Sections → Pages
Right Panel	Context-aware property inspector (changes based on selected element)
View Types	List, Chart, Dashboard (composable elements)
Share Model	"Share interface" — published interfaces are shared independently

---

2. Evaluation: Do We Need This?

✅ YES — This is a Core Requirement

This is not a "nice-to-have". The Design → Stage → Publish pattern is essential for ObjectUI's positioning as a "JSON-to-Shadcn" SDUI engine. Here's why:

Reason	Explanation
Enterprise Readiness	No enterprise will deploy UI changes directly to production. A staging/publish gate is table stakes.
Our Differentiator	Airtable's Interface Designer proves the market wants visual, metadata-driven UI building. We provide the same experience but with Shadcn-quality output instead of Airtable's locked-in components.
Schema-Driven by Nature	Our JSON protocol (UIComponent) already IS the "staged" artifact. We just need to formalize the lifecycle around it.
Backend Agnostic	Unlike Airtable (tied to its own DB), we can connect to any data source — making our version more powerful.

Risk if we DON'T implement:

• ObjectUI becomes "just a renderer" — a commodity.
• No competitive moat against Retool, Appsmith, or ToolJet.

---

3. Architecture Design: Interface Lifecycle Protocol

3.1 The Three-Phase Lifecycle

┌─────────┐     save      ┌─────────┐    publish    ┌─────────────┐
│  DESIGN │ ────────────► │  DRAFT  │ ────────────► │  PUBLISHED  │
│  (edit) │               │ (staged)│               │ (immutable) │
└─────────┘               └─────────┘               └─────────────┘
     ▲                         │                          │
     │          revert         │       rollback           │
     └─────────────────────────┘◄─────────────────────────┘

Phase	Description	Storage
Design	Active editing. Blue dashed borders (as in screenshots). Auto-saved to draft.	Mutable draft record
Draft (Staged)	Preview-ready snapshot. "Interface has unpublished changes" banner.	Versioned draft snapshot
Published	Immutable, live version. "Last published Feb 21, 2026". End-users see this.	Immutable version record

3.2 Protocol Additions to @objectstack/spec

Let me first check the current state of both repositories:Now let me look at the existing UI protocol schemas in the spec repo and the current packages structure in objectui to understand the current state:Now let me dig deeper into the specific interface and designer-related schemas and the gap analysis document to understand the current state of the publish/staging flow.Now let me check the current state of the app.zod.ts in the spec repo since the gap analysis document mentions it was superseded, and also look at the plugin-designer package for the existing design-time tooling:Now I have a comprehensive picture of both repositories. Let me synthesize this into a thorough assessment.

---

Assessment: Airtable-Style App Design Pattern for ObjectStack

Overview: What You're Asking

Based on the Airtable screenshots (Image 1: Customer List Interface with Grid/Tabs, Image 2: Performance Dashboard with Charts), you're evaluating the Design → Stage → Publish lifecycle pattern — specifically:

1. Design Mode — Drag-and-drop interface builder with right-panel property inspector
2. Staging — "Unpublished changes" state where edits are buffered before going live
3. Publish — One-click deployment to end-users (Airtable's red "Publish" button)

---

1. Current State Assessment

✅ What's Already Done (Spec Protocol — objectstack-ai/spec)

The spec repo has extensive schema coverage for the Airtable Interface model. Per the gap analysis doc:

Area	Status	Schema Location
Interface as first-class entity	✅	InterfaceSchema in src/ui/interface.zod.ts
16 page types (grid, list, dashboard, kanban, etc.)	✅	PageTypeSchema in src/ui/page.zod.ts
Element palette (text, number, image, divider, button, filter, form, record_picker)	✅	PageComponentType extensions
Per-element data binding	✅	ElementDataSourceSchema
Record Review workflow	✅	RecordReviewConfigSchema
Free-form canvas	✅	BlankPageLayoutSchema
Builder config (snap, zoom, palette, layers)	✅	InterfaceBuilderConfigSchema
Sharing & embedding	✅	SharingConfigSchema, EmbedConfigSchema
Interface page config (hierarchy, filters, appearance)	✅	InterfacePageConfigSchema
App → Interface navigation bridge	✅	App.interfaces[], InterfaceNavItemSchema

❌ What's Missing — The Draft→Published Lifecycle

This is the critical gap. The Airtable screenshots clearly show:

• Image 1: "No changes · Last published Feb 21, 2026" — a clean published state
• Image 2: "Interface has unpublished changes · Last published Feb 18, 2026" — a dirty draft state with "All changes saved" auto-save

This versioning/staging/publish lifecycle is explicitly listed as a Phase D (v4.1) TODO in the roadmap:

"Interface versioning (draft → published → archived lifecycle)" — Section 7.4

❌ What's Missing in ObjectUI (Runtime — objectstack-ai/objectui)

The objectui repo has the AppCreationWizard (4-step wizard for creating apps) and WorkflowDesigner with save/publish buttons, but lacks:

Gap	Description
Interface Builder UI	Drag-and-drop canvas is not built (confirmed: "Implement Studio Interface Builder UI — runtime task")
Draft/Publish state management	No useDesignerState() hook or store for tracking dirty/clean/published states
Auto-save mechanism	Airtable auto-saves all design changes to a draft — no such mechanism exists
Publish flow	No "Publish" button that snapshots current draft to a published version
Version comparison	No diff between published and draft versions
Preview mode	DesignPreviewSchema defined in spec but not built in runtime

---

2. Recommended Architecture for Design → Stage → Publish

2.1 Protocol Layer (spec repo)

We need a new Interface Versioning Protocol. Here's the proposed schema:

// Proposed: packages/spec/src/ui/interface-lifecycle.zod.ts

import { z } from 'zod';

/**
 * Interface Lifecycle Status
 * Models Airtable's "No changes / Unpublished changes / Last published" states.
 */
export const InterfaceLifecycleStatus = z.enum([
  'draft',       // Never published, work in progress
  'published',   // Live version matches last edit (clean)
  'modified',    // Has unpublished changes (dirty)
  'archived',    // Soft-deleted / historical
]);

/**
 * Interface Version Snapshot
 * Immutable snapshot of an interface at a point in time.
 */
export const InterfaceVersionSchema = z.object({
  /** Version number (auto-incrementing) */
  version: z.number().int().min(1),

  /** Snapshot of the full interface definition (pages, elements, config) */
  snapshot: z.any().describe('Serialized InterfaceSchema at publish time'),

  /** Who published this version */
  publishedBy: z.string().optional(),

  /** When this version was published */
  publishedAt: z.string().datetime(),

  /** Optional release note */
  changeNote: z.string().optional(),
});

/**
 * Interface Draft State
 * Tracks the working copy and its relationship to the published version.
 */
export const InterfaceDraftStateSchema = z.object({
  /** Current lifecycle status */
  status: InterfaceLifecycleStatus,

  /** Working copy (auto-saved, mutable) */
  draft: z.any().describe('Current working InterfaceSchema'),

  /** Last published version number */
  publishedVersion: z.number().int().optional(),

  /** Last published timestamp */
  lastPublishedAt: z.string().datetime().optional(),

  /** Last auto-save timestamp */
  lastSavedAt: z.string().datetime().optional(),

  /** Whether the draft differs from the published version */
  hasUnpublishedChanges: z.boolean().default(false),

  /** Version history (ordered newest first) */
  versionHistory: z.array(InterfaceVersionSchema).optional(),
});

2.2 Runtime Layer (objectui repo)

A. State Store (Zustand)

// Proposed: packages/plugin-designer/src/stores/useInterfaceDesigner.ts

import { create } from 'zustand';

interface InterfaceDesignerState {
  // === Lifecycle ===
  status: 'draft' | 'published' | 'modified' | 'archived';
  publishedVersion: number | null;
  lastPublishedAt: string | null;
  lastSavedAt: string | null;
  hasUnpublishedChanges: boolean;

  // === Draft ===
  draft: InterfaceSchema | null;
  
  // === Actions ===
  /** Update draft (triggers auto-save debounce) */
  updateDraft: (partial: Partial<InterfaceSchema>) => void;
  
  /** Publish current draft → new published version */
  publish: () => Promise<void>;
  
  /** Revert draft to last published version */
  revertToPublished: () => void;
  
  /** Load interface (hydrate from server) */
  loadInterface: (id: string) => Promise<void>;
}

B. Auto-Save Hook

// Proposed: packages/plugin-designer/src/hooks/useAutoSave.ts

/**
 * Auto-save hook that debounces draft changes and persists them.
 * Mirrors Airtable's "All changes saved" behavior.
 */
export function useAutoSave(draft: InterfaceSchema | null, options?: {
  debounceMs?: number;  // default 2000
  onSave?: (draft: InterfaceSchema) => Promise<void>;
  onStatusChange?: (status: 'saving' | 'saved' | 'error') => void;
}) {
  // Debounced save logic
  // Returns: { saveStatus: 'saving' | 'saved' | 'error', lastSavedAt: Date | null }
}

C. Publish Flow UI

The top bar should mirror Airtable's pattern:

┌─────────────────────────────────────────────────────────────────┐
│  Previewing as: [Yourself ▼]                                    │
│                                                                 │
│  [status indicator]                         [Publish] [Share ▼] │
│  "Interface has unpublished changes ·                           │
│   Last published Feb 18, 2026"                                  │
└─────────────────────────────────────────────────────────────────┘

States to render:

• Clean: "No changes · Last published {date}" — Publish button disabled
• Dirty: "Interface has unpublished changes · Last published {date}" — Publish button red/active
• Saving: "All changes saved" indicator (green checkmark)
• Never published: "Draft · Never published" — Publish button active

2.3 Data Flow

┌──────────────┐     Auto-Save (2s debounce)     ┌──────────────┐
│  User edits  │ ──────────────────────────────── │ Draft (DB)   │
│  in Designer │                                  │ status:      │
│              │                                  │ 'modified'   │
└──────────────┘                                  └──────────────┘
                                                         │
                                                   [Publish] click
                                                         │
                                                         ▼
                                                  ┌──────────────┐
                                                  │ Published    │
                                                  │ Version N+1  │
                                                  │ (immutable   │
                                                  │  snapshot)   │
                                                  └──────────────┘
                                                         │
                                                    Rendered to
                                                    end-users
                                                         │
                                                         ▼
                                                  ┌──────────────┐
                                                  │  Runtime     │
                                                  │  Renderer    │
                                                  │  (published  │
                                                  │   version    │
                                                  │   only)      │
                                                  └──────────────┘

---

3. Gap-by-Gap Implementation Plan

#	Gap	Where	Effort	Priority
L1	InterfaceLifecycleStatus + InterfaceVersionSchema	spec → src/ui/interface-lifecycle.zod.ts	1 week	🔴 P0
L2	InterfaceDraftStateSchema with version history	spec → same file	1 week	🔴 P0
L3	useInterfaceDesigner Zustand store	objectui → packages/plugin-designer	2 weeks	🔴 P0
L4	Auto-save hook (useAutoSave)	objectui → packages/plugin-designer	1 week	🔴 P0
L5	Publish flow UI (top bar + confirmation dialog)	objectui → packages/plugin-designer	1 week	🔴 P0
L6	Version history panel (view past snapshots)	objectui → packages/plugin-designer	1 week	🟡 P1
L7	Revert to published version	objectui → packages/plugin-designer	3 days	🟡 P1
L8	Diff view (draft vs published)	objectui → packages/plugin-designer	2 weeks	🟡 P1
L9	"Preview as" user impersonation	objectui → packages/plugin-designer	2 weeks	🟡 P1
L10	Interface Builder drag-and-drop canvas	objectui → packages/plugin-designer	6–8 weeks	🔴 P0

Total estimated effort: ~12–16 weeks for full Airtable-parity design/stage/publish lifecycle.

---

4. Verdict: Is It Needed?

Yes, absolutely — this is a P0 strategic requirement.

Reasoning:

1. It's the Add metamodel interfaces for ObjectQL/ObjectUI contract #1 differentiator for low-code platforms. Every competitor (Airtable, Retool, Appsmith, Salesforce Lightning) has a design → preview → publish flow. Without it, ObjectUI is a component library, not an app builder.

2. The spec is already 80% there. Phases A, B, and C of the Airtable gap analysis are largely complete in the spec repo. The missing 20% is the lifecycle protocol (draft/publish) and the runtime builder UI.

3. It directly maps to your screenshots. Both images show the exact UX pattern — the top bar with publish state, right-panel property inspector, left sidebar navigation tree — all of which have spec schemas but no runtime implementation.

4. The existing plugin-designer package is the natural home. It already has AppCreationWizard, which proves the wizard/design pattern. Extending it with the Interface Builder + Publish flow is architecturally clean.

How to Prioritize

Phase	What	Timeline
Phase 1	Define InterfaceLifecycleStatus protocol in spec. Build useInterfaceDesigner store + auto-save + publish flow in objectui.	4 weeks
Phase 2	Build Interface Builder canvas (drag-and-drop elements from palette, property panel). This is the biggest chunk.	6–8 weeks
Phase 3	Version history, diff view, preview-as-user, revert.	4 weeks

Would you like me to create issues in one or both repos to track this work?

[hotlong]

Good point. Let me examine the existing API protocol and service contracts in the spec repo to understand how the lifecycle should be modeled end-to-end.非常好的提醒。你说得对 — spec 中定义的协议不能仅停留在 Zod schema 层面，必须同时考虑 API 端点 和 Runtime 服务端合约。让我基于现有架构模式做完整的补充设计。

---

补充评估：Interface Lifecycle 的 API + Runtime 服务端协议

当前架构模式回顾

ObjectStack 的协议设计遵循一个清晰的三层模式：

┌─────────────────────────────────────────────────────────────────────┐
│  1. Zod Schema Layer    (packages/spec/src/)                       │
│     定义数据结构 → DeployBundleSchema, ViewSchema, AppSchema       │
├─────────────────────────────────────────────────────────────────────┤
│  2. Service Contract    (packages/spec/src/contracts/)             │
│     定义接口合约 → IMetadataService, IDeployPipelineService       │
├─────────────────────────────────────────────────────────────────────┤
│  3. API Protocol        (packages/spec/src/api/)                   │
│     定义 REST 端点 → protocol.zod.ts, plugin-rest-api.zod.ts      │
│     定义 Protocol接口 → ObjectStackProtocol                       │
├─────────────────────────────────────────────────────────────────────┤
│  4. Runtime Implementation (packages/runtime/, packages/metadata/) │
│     实现服务 → MetadataManager, HttpDispatcher                     │
└─────────────────────────────────────────────────────────────────────┘

参考已有的模式（IDeployPipelineService + deploy-bundle.zod.ts + ObjectStackProtocol），Interface Lifecycle 需要在 每一层 都有对应产出物。

---

完整协议设计

Layer 1: Zod Schema — interface-lifecycle.zod.ts

// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.

import { z } from 'zod';

/**
 * Interface Lifecycle Protocol
 *
 * Defines the draft → published → archived lifecycle for Interfaces,
 * mirroring Airtable's "Design / Unpublished Changes / Publish" pattern.
 *
 * Architecture alignment:
 * - Airtable: Interface has "unpublished changes" state, one-click Publish
 * - Salesforce: FlexiPage has "Draft" vs "Active" activation status
 * - Retool: Apps have "Edit mode" → "Deploy" flow with version history
 *
 * Data flow:
 *   Designer edits → Auto-save to Draft → [Publish] → Snapshot to Version → Serve Published
 *
 * The runtime serves ONLY the published version to end-users.
 * Designers see the draft version in the builder.
 */

// ==========================================================================
// 1. Lifecycle Status
// ==========================================================================

/**
 * Interface lifecycle status.
 *
 * - `draft`: Never published, work in progress
 * - `published`: Live version matches last edit (clean state)
 * - `modified`: Has unpublished changes since last publish (dirty state)
 * - `archived`: Soft-deleted, not accessible to end-users
 */
export const InterfaceLifecycleStatusEnum = z.enum([
  'draft',
  'published',
  'modified',
  'archived',
]);
export type InterfaceLifecycleStatus = z.infer<typeof InterfaceLifecycleStatusEnum>;

// ==========================================================================
// 2. Version Snapshot
// ==========================================================================

/**
 * Immutable snapshot of an interface at publish time.
 * Once created, a version is never modified.
 */
export const InterfaceVersionSchema = z.object({
  /** Auto-incrementing version number */
  version: z.number().int().min(1).describe('Version number'),

  /** Full serialized interface definition at publish time */
  snapshot: z.record(z.string(), z.unknown())
    .describe('Serialized InterfaceSchema at publish time'),

  /** User who published this version */
  publishedBy: z.string().optional().describe('User ID of publisher'),

  /** Publish timestamp (ISO 8601) */
  publishedAt: z.string().datetime().describe('When this version was published'),

  /** Optional release note */
  changeNote: z.string().optional().describe('Release note for this version'),

  /** SHA256 of snapshot for integrity checking */
  checksum: z.string().optional().describe('SHA256 checksum of snapshot'),
});
export type InterfaceVersion = z.infer<typeof InterfaceVersionSchema>;

// ==========================================================================
// 3. Draft State (Mutable Working Copy)
// ==========================================================================

/**
 * Interface Draft State — tracks the mutable working copy
 * and its relationship to the published version.
 *
 * This is the primary state object persisted by the runtime.
 */
export const InterfaceDraftStateSchema = z.object({
  /** Interface name (immutable identifier) */
  interfaceName: z.string().regex(/^[a-z_][a-z0-9_]*$/)
    .describe('Interface identifier (snake_case)'),

  /** Current lifecycle status */
  status: InterfaceLifecycleStatusEnum.describe('Current lifecycle status'),

  /** Mutable working copy (auto-saved) */
  draft: z.record(z.string(), z.unknown())
    .describe('Current working InterfaceSchema'),

  /** Currently published version number (null if never published) */
  publishedVersion: z.number().int().optional()
    .describe('Last published version number'),

  /** Snapshot of the published version (for diff/revert) */
  publishedSnapshot: z.record(z.string(), z.unknown()).optional()
    .describe('Snapshot of the currently live version'),

  /** Last publish timestamp */
  lastPublishedAt: z.string().datetime().optional()
    .describe('When last published'),

  /** Last auto-save timestamp */
  lastSavedAt: z.string().datetime().optional()
    .describe('When draft was last auto-saved'),

  /** Whether the draft differs from published */
  hasUnpublishedChanges: z.boolean().default(false)
    .describe('Whether draft differs from published version'),
});
export type InterfaceDraftState = z.infer<typeof InterfaceDraftStateSchema>;

// ==========================================================================
// 4. Publish Request / Response
// ==========================================================================

/**
 * Publish Interface Request
 */
export const PublishInterfaceRequestSchema = z.object({
  /** Interface name */
  interfaceName: z.string().describe('Interface to publish'),

  /** Optional release note */
  changeNote: z.string().optional().describe('Release note'),

  /** Whether to validate before publishing */
  validate: z.boolean().default(true).describe('Validate interface before publish'),
});
export type PublishInterfaceRequest = z.infer<typeof PublishInterfaceRequestSchema>;

/**
 * Publish Interface Response
 */
export const PublishInterfaceResponseSchema = z.object({
  /** Whether publish succeeded */
  success: z.boolean(),

  /** New version number */
  version: z.number().int().optional(),

  /** Publish timestamp */
  publishedAt: z.string().datetime().optional(),

  /** Validation errors (if validate=true and failed) */
  validationErrors: z.array(z.object({
    path: z.string(),
    message: z.string(),
  })).optional(),
});
export type PublishInterfaceResponse = z.infer<typeof PublishInterfaceResponseSchema>;

// ==========================================================================
// 5. Revert / Rollback
// ==========================================================================

/**
 * Revert Draft to Published Request
 */
export const RevertDraftRequestSchema = z.object({
  interfaceName: z.string().describe('Interface to revert'),
  /** Revert to a specific version (defaults to current published) */
  targetVersion: z.number().int().optional()
    .describe('Version to revert to (default: current published)'),
});

export const RevertDraftResponseSchema = z.object({
  success: z.boolean(),
  revertedToVersion: z.number().int().optional(),
});

// ==========================================================================
// 6. Version History
// ==========================================================================

/**
 * List Version History Request
 */
export const ListVersionsRequestSchema = z.object({
  interfaceName: z.string().describe('Interface name'),
  limit: z.number().int().min(1).max(100).default(20)
    .describe('Max versions to return'),
  offset: z.number().int().min(0).default(0),
});

export const ListVersionsResponseSchema = z.object({
  interfaceName: z.string(),
  versions: z.array(InterfaceVersionSchema),
  total: z.number().int(),
});

// ==========================================================================
// 7. Diff
// ==========================================================================

/**
 * Diff between draft and published version.
 */
export const InterfaceDiffSchema = z.object({
  interfaceName: z.string(),
  hasChanges: z.boolean(),
  changes: z.array(z.object({
    path: z.string().describe('JSON path of change (e.g. "pages[0].label")'),
    type: z.enum(['added', 'modified', 'removed']),
    oldValue: z.unknown().optional(),
    newValue: z.unknown().optional(),
  })),
  summary: z.object({
    pagesAdded: z.number().int().default(0),
    pagesRemoved: z.number().int().default(0),
    pagesModified: z.number().int().default(0),
    elementsAdded: z.number().int().default(0),
    elementsRemoved: z.number().int().default(0),
    elementsModified: z.number().int().default(0),
  }),
});
export type InterfaceDiff = z.infer<typeof InterfaceDiffSchema>;

Layer 2: Service Contract — IInterfaceLifecycleService

参照 IDeployPipelineService 和 IAppLifecycleService 的模式：

// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.

/**
 * IInterfaceLifecycleService - Interface Design/Stage/Publish Contract
 *
 * Manages the full lifecycle of Airtable-style Interfaces:
 * 1. Create/load draft
 * 2. Auto-save draft changes
 * 3. Diff draft vs published
 * 4. Validate before publish
 * 5. Publish (snapshot draft → new version)
 * 6. Revert to previous version
 * 7. Archive / restore
 *
 * Aligned with CoreServiceName 'interface-lifecycle' in core-services.zod.ts.
 *
 * ## Relationship to IMetadataService
 * - IMetadataService stores the *published* interface definition (type='interface')
 * - IInterfaceLifecycleService manages the *draft* + *version history*
 * - On publish, this service calls IMetadataService.register('interface', name, snapshot)
 *
 * ## Relationship to IDeployPipelineService
 * - Interface publish does NOT trigger DDL changes (it's UI metadata only)
 * - But if interface references new objects/fields, IDeployPipelineService handles that separately
 */

import type {
  InterfaceDraftState,
  InterfaceVersion,
  InterfaceDiff,
  PublishInterfaceRequest,
  PublishInterfaceResponse,
  InterfaceLifecycleStatus,
} from '../ui/interface-lifecycle.zod.js';

// ==========================================================================
// Service Interface
// ==========================================================================

export interface IInterfaceLifecycleService {

  // ==========================================
  // Draft Management
  // ==========================================

  /**
   * Get the current draft state of an interface.
   * Returns the mutable working copy + lifecycle status.
   *
   * @param tenantId - Tenant context
   * @param interfaceName - Interface identifier
   * @returns Draft state, or null if not found
   */
  getDraftState(tenantId: string, interfaceName: string): Promise<InterfaceDraftState | null>;

  /**
   * Save draft changes (auto-save endpoint).
   * Debounced by the client, but the server accepts any frequency.
   * Updates `lastSavedAt`, sets `hasUnpublishedChanges = true`,
   * transitions status to 'modified' if currently 'published'.
   *
   * @param tenantId - Tenant context
   * @param interfaceName - Interface identifier
   * @param draft - Partial or full draft update
   * @returns Updated draft state
   */
  saveDraft(
    tenantId: string,
    interfaceName: string,
    draft: Record<string, unknown>,
  ): Promise<InterfaceDraftState>;

  /**
   * Create a new interface in draft status.
   *
   * @param tenantId - Tenant context
   * @param interfaceName - Interface identifier (snake_case)
   * @param initialDraft - Initial interface definition
   * @returns Created draft state
   */
  createDraft(
    tenantId: string,
    interfaceName: string,
    initialDraft: Record<string, unknown>,
  ): Promise<InterfaceDraftState>;

  // ==========================================
  // Publish / Revert
  // ==========================================

  /**
   * Publish the current draft as a new version.
   * 1. Validates draft (if request.validate = true)
   * 2. Creates immutable version snapshot
   * 3. Updates metadata registry (IMetadataService.register)
   * 4. Transitions status to 'published'
   * 5. Clears hasUnpublishedChanges
   *
   * @param tenantId - Tenant context
   * @param request - Publish request with optional change note
   * @returns Publish result with version number
   */
  publish(tenantId: string, request: PublishInterfaceRequest): Promise<PublishInterfaceResponse>;

  /**
   * Revert draft to a published version.
   * Replaces draft content with the snapshot of the target version.
   * Does NOT change the published version — only resets the draft.
   *
   * @param tenantId - Tenant context
   * @param interfaceName - Interface identifier
   * @param targetVersion - Version to revert to (default: current published)
   * @returns Success status
   */
  revertDraft(
    tenantId: string,
    interfaceName: string,
    targetVersion?: number,
  ): Promise<{ success: boolean; revertedToVersion?: number }>;

  // ==========================================
  // Diff
  // ==========================================

  /**
   * Compute diff between current draft and published version.
   * Used by the UI to show "unpublished changes" summary.
   *
   * @param tenantId - Tenant context
   * @param interfaceName - Interface identifier
   * @returns Structured diff with change details
   */
  getDiff(tenantId: string, interfaceName: string): Promise<InterfaceDiff>;

  // ==========================================
  // Version History
  // ==========================================

  /**
   * List published version history for an interface.
   *
   * @param tenantId - Tenant context
   * @param interfaceName - Interface identifier
   * @param limit - Max versions to return
   * @param offset - Pagination offset
   * @returns Array of version snapshots (newest first)
   */
  listVersions(
    tenantId: string,
    interfaceName: string,
    limit?: number,
    offset?: number,
  ): Promise<{ versions: InterfaceVersion[]; total: number }>;

  /**
   * Get a specific version snapshot.
   *
   * @param tenantId - Tenant context
   * @param interfaceName - Interface identifier
   * @param version - Version number
   * @returns Version snapshot
   */
  getVersion(
    tenantId: string,
    interfaceName: string,
    version: number,
  ): Promise<InterfaceVersion | null>;

  // ==========================================
  // Lifecycle Operations
  // ==========================================

  /**
   * Archive an interface (soft delete).
   * Removes from end-user access but preserves all versions.
   */
  archive(tenantId: string, interfaceName: string): Promise<void>;

  /**
   * Restore an archived interface.
   * Re-publishes the last published version.
   */
  restore(tenantId: string, interfaceName: string): Promise<void>;

  /**
   * Delete an interface permanently.
   * Removes draft, all versions, and metadata registration.
   * Requires confirmation (irreversible).
   */
  deletePermanently(tenantId: string, interfaceName: string): Promise<void>;
}

Layer 3: API Protocol — REST 端点 + ObjectStackProtocol 扩展

参照 protocol.zod.ts 和 plugin-rest-api.zod.ts：

// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.

/**
 * Interface Lifecycle REST API Definition
 *
 * Endpoint registration for the plugin-rest-api system.
 * Maps IInterfaceLifecycleService methods to HTTP endpoints.
 *
 * Follows the same pattern as View Management endpoints in protocol.zod.ts.
 */

// ==========================================================================
// REST Endpoint Registry (for plugin-rest-api.zod.ts)
// ==========================================================================

/**
 * Interface Lifecycle API Plugin Route Group
 *
 * Prefix: /api/v1/interfaces
 * Service: interface-lifecycle
 *
 * Endpoint Map:
 * ┌─────────────────────────────────────────────────────────────────────────┐
 * │  方法   │  HTTP   │  Endpoint                                         │
 * ├─────────┼─────────┼───────────────────────────────────────────────────┤
 * │ Draft   │  GET    │  /api/v1/interfaces/:name/draft                   │
 * │ Save    │  PUT    │  /api/v1/interfaces/:name/draft                   │
 * │ Create  │  POST   │  /api/v1/interfaces                               │
 * │ Publish │  POST   │  /api/v1/interfaces/:name/publish                 │
 * │ Revert  │  POST   │  /api/v1/interfaces/:name/revert                  │
 * │ Diff    │  GET    │  /api/v1/interfaces/:name/diff                    │
 * │ List V  │  GET    │  /api/v1/interfaces/:name/versions                │
 * │ Get V   │  GET    │  /api/v1/interfaces/:name/versions/:version       │
 * │ Archive │  POST   │  /api/v1/interfaces/:name/archive                 │
 * │ Restore │  POST   │  /api/v1/interfaces/:name/restore                 │
 * │ Delete  │  DELETE │  /api/v1/interfaces/:name                         │
 * │ List    │  GET    │  /api/v1/interfaces                               │
 * │ Published│ GET    │  /api/v1/interfaces/:name/published               │
 * └─────────┴─────────┴───────────────────────────────────────────────────┘
 *
 * 注意: 端用户 runtime 只需要 GET /published 端点。
 * 设计器需要所有端点。
 */
export const INTERFACE_LIFECYCLE_ROUTES = {
  prefix: '/api/v1/interfaces',
  service: 'interface-lifecycle',
  category: 'ui',
  authRequired: true,
  endpoints: [
    // --- Draft Management ---
    {
      method: 'GET' as const,
      path: '/:name/draft',
      handler: 'getDraftState',
      summary: 'Get current draft state of an interface',
      tags: ['Interface Lifecycle'],
      responseSchema: 'InterfaceDraftStateSchema',
    },
    {
      method: 'PUT' as const,
      path: '/:name/draft',
      handler: 'saveDraft',
      summary: 'Auto-save draft changes',
      description: 'Called by the designer on debounced edit. Server always accepts.',
      tags: ['Interface Lifecycle'],
      requestSchema: 'InterfaceDraftStateSchema',
      responseSchema: 'InterfaceDraftStateSchema',
    },
    {
      method: 'POST' as const,
      path: '',
      handler: 'createDraft',
      summary: 'Create new interface in draft status',
      tags: ['Interface Lifecycle'],
      responseSchema: 'InterfaceDraftStateSchema',
    },

    // --- Publish / Revert ---
    {
      method: 'POST' as const,
      path: '/:name/publish',
      handler: 'publish',
      summary: 'Publish current draft as new version',
      description: 'Validates, snapshots, registers in metadata, transitions to published.',
      tags: ['Interface Lifecycle'],
      requestSchema: 'PublishInterfaceRequestSchema',
      responseSchema: 'PublishInterfaceResponseSchema',
    },
    {
      method: 'POST' as const,
      path: '/:name/revert',
      handler: 'revertDraft',
      summary: 'Revert draft to a published version',
      tags: ['Interface Lifecycle'],
      requestSchema: 'RevertDraftRequestSchema',
      responseSchema: 'RevertDraftResponseSchema',
    },

    // --- Diff ---
    {
      method: 'GET' as const,
      path: '/:name/diff',
      handler: 'getDiff',
      summary: 'Compute diff between draft and published',
      tags: ['Interface Lifecycle'],
      responseSchema: 'InterfaceDiffSchema',
    },

    // --- Version History ---
    {
      method: 'GET' as const,
      path: '/:name/versions',
      handler: 'listVersions',
      summary: 'List published version history',
      tags: ['Interface Lifecycle'],
      responseSchema: 'ListVersionsResponseSchema',
    },
    {
      method: 'GET' as const,
      path: '/:name/versions/:version',
      handler: 'getVersion',
      summary: 'Get a specific version snapshot',
      tags: ['Interface Lifecycle'],
      responseSchema: 'InterfaceVersionSchema',
    },

    // --- Lifecycle ---
    {
      method: 'POST' as const,
      path: '/:name/archive',
      handler: 'archive',
      summary: 'Archive interface (soft delete)',
      tags: ['Interface Lifecycle'],
    },
    {
      method: 'POST' as const,
      path: '/:name/restore',
      handler: 'restore',
      summary: 'Restore archived interface',
      tags: ['Interface Lifecycle'],
    },
    {
      method: 'DELETE' as const,
      path: '/:name',
      handler: 'deletePermanently',
      summary: 'Permanently delete interface and all versions',
      tags: ['Interface Lifecycle'],
    },

    // --- Runtime (end-user facing) ---
    {
      method: 'GET' as const,
      path: '',
      handler: 'listInterfaces',
      summary: 'List all interfaces (with status)',
      tags: ['Interface Lifecycle'],
      cacheable: true,
      cacheTtl: 60,
    },
    {
      method: 'GET' as const,
      path: '/:name/published',
      handler: 'getPublished',
      summary: 'Get the published version of an interface (runtime)',
      description: 'This is the ONLY endpoint end-users need. Returns the published snapshot.',
      tags: ['Interface Runtime'],
      cacheable: true,
      cacheTtl: 300,
    },
  ],
} as const;

Layer 3b: ObjectStackProtocol 扩展

需要将新方法添加到 ObjectStackProtocol 接口（protocol.zod.ts）：

// Addition to ObjectStackProtocol interface in protocol.zod.ts

export interface ObjectStackProtocol {
  // ... existing methods ...

  // Interface Lifecycle (optional — provided by interface-lifecycle plugin)
  getInterfaceDraft?(request: { interfaceName: string }): Promise<InterfaceDraftState | null>;
  saveInterfaceDraft?(request: { interfaceName: string; draft: Record<string, unknown> }): Promise<InterfaceDraftState>;
  createInterface?(request: { interfaceName: string; draft: Record<string, unknown> }): Promise<InterfaceDraftState>;
  publishInterface?(request: PublishInterfaceRequest): Promise<PublishInterfaceResponse>;
  revertInterfaceDraft?(request: { interfaceName: string; targetVersion?: number }): Promise<{ success: boolean }>;
  getInterfaceDiff?(request: { interfaceName: string }): Promise<InterfaceDiff>;
  listInterfaceVersions?(request: { interfaceName: string; limit?: number; offset?: number }): Promise<{ versions: InterfaceVersion[]; total: number }>;
  getInterfaceVersion?(request: { interfaceName: string; version: number }): Promise<InterfaceVersion | null>;
  getPublishedInterface?(request: { interfaceName: string }): Promise<Record<string, unknown> | null>;
}

Layer 4: Runtime 实现参考架构

// Pseudo-code: Runtime implementation reference

/**
 * Interface Lifecycle Service Implementation
 *
 * Storage architecture:
 * - Drafts: metadata table (type='interface_draft', scope='platform')
 * - Versions: metadata table (type='interface_version', scope='system')
 * - Published: metadata table (type='interface', scope='platform') ← IMetadataService
 *
 * The implementation uses IMetadataService for persistence:
 * - Draft storage: metadata.register('interface_draft', name, draftState)
 * - Version storage: metadata.register('interface_version', `${name}__v${version}`, snapshot)
 * - Published registration: metadata.register('interface', name, publishedSnapshot)
 */

export class InterfaceLifecycleServiceImpl implements IInterfaceLifecycleService {
  constructor(
    private metadata: IMetadataService,
    private logger: Logger,
  ) {}

  async getDraftState(tenantId: string, interfaceName: string): Promise<InterfaceDraftState | null> {
    return await this.metadata.get('interface_draft', interfaceName) as InterfaceDraftState | null;
  }

  async saveDraft(tenantId: string, interfaceName: string, draft: Record<string, unknown>): Promise<InterfaceDraftState> {
    const current = await this.getDraftState(tenantId, interfaceName);
    if (!current) throw new Error(`Interface ${interfaceName} not found`);

    const updated: InterfaceDraftState = {
      ...current,
      draft,
      lastSavedAt: new Date().toISOString(),
      hasUnpublishedChanges: true,
      status: current.status === 'published' ? 'modified' : current.status,
    };

    await this.metadata.register('interface_draft', interfaceName, updated);
    return updated;
  }

  async publish(tenantId: string, request: PublishInterfaceRequest): Promise<PublishInterfaceResponse> {
    const state = await this.getDraftState(tenantId, request.interfaceName);
    if (!state) return { success: false, validationErrors: [{ path: '', message: 'Not found' }] };

    // 1. Validate (optional)
    if (request.validate) {
      const validation = await this.validateInterface(state.draft);
      if (!validation.valid) {
        return { success: false, validationErrors: validation.errors };
      }
    }

    // 2. Create version snapshot
    const newVersion = (state.publishedVersion ?? 0) + 1;
    const publishedAt = new Date().toISOString();
    const versionEntry: InterfaceVersion = {
      version: newVersion,
      snapshot: structuredClone(state.draft),
      publishedBy: tenantId, // would use actual user ID
      publishedAt,
      changeNote: request.changeNote,
    };

    // 3. Store version
    await this.metadata.register('interface_version', `${request.interfaceName}__v${newVersion}`, versionEntry);

    // 4. Register published snapshot in metadata (this is what runtime serves)
    await this.metadata.register('interface', request.interfaceName, state.draft);

    // 5. Update draft state
    const updated: InterfaceDraftState = {
      ...state,
      status: 'published',
      publishedVersion: newVersion,
      publishedSnapshot: structuredClone(state.draft),
      lastPublishedAt: publishedAt,
      hasUnpublishedChanges: false,
    };
    await this.metadata.register('interface_draft', request.interfaceName, updated);

    return { success: true, version: newVersion, publishedAt };
  }

  // ... other methods follow same pattern ...
}

---

与现有系统的集成点

与 IMetadataService 的关系

┌─────────────────────────────────────┐
│  IInterfaceLifecycleService         │  ← 管理 Draft + 版本 + Publish 流
│  (新增)                             │
│                                     │
│  Uses IMetadataService internally:  │
│  ┌───────────────────────────────┐  │
│  │ type='interface_draft'  Draft │  │  ← 可变工作副本
│  │ type='interface_version' Snap │  │  ← 不可变版本快照
│  │ type='interface'  Published   │  │  ← 运行时提供给终端用户
│  └───────────────────────────────┘  │
└─────────────��───────────────────────┘
         │
         │ publish() 触发
         ▼
┌─────────────────────────────────────┐
│  IMetadataService                   │  ← 已有，不需要修改
│  (现有)                             │
│                                     │
│  register('interface', name, data)  │  ← Publish 时注册
│  get('interface', name)             │  ← Runtime 查询
│  watch('interface', callback)       │  ← 实时更新通知
└─────────────────────────────────────┘

与 HttpDispatcher 的关系

参照现有的 handleMetadata：

// 在 HttpDispatcher 中添加路由分发

async handleInterfaces(path: string, context: HttpProtocolContext, method: string, body?: any): Promise<HttpDispatcherResult> {
  const lifecycleService = await this.kernel.context.getService('interface-lifecycle');

  // PUT /api/v1/interfaces/:name/draft → saveDraft
  // POST /api/v1/interfaces/:name/publish → publish
  // GET /api/v1/interfaces/:name/published → getPublished (cached)
  // ... etc
}

与 @objectstack/client 的关系

参照 CLIENT_SPEC_COMPLIANCE.md，需要在 client SDK 中添加：

// @objectstack/client 扩展

interface ObjectStackClient {
  // ... existing ...

  interfaces: {
    /** Get draft state (designer only) */
    getDraft(name: string): Promise<InterfaceDraftState>;
    /** Save draft (auto-save from designer) */
    saveDraft(name: string, draft: Record<string, unknown>): Promise<InterfaceDraftState>;
    /** Publish current draft */
    publish(name: string, options?: { changeNote?: string }): Promise<PublishInterfaceResponse>;
    /** Revert draft to published version */
    revert(name: string, targetVersion?: number): Promise<void>;
    /** Get diff between draft and published */
    diff(name: string): Promise<InterfaceDiff>;
    /** List version history */
    versions(name: string, options?: { limit?: number; offset?: number }): Promise<{ versions: InterfaceVersion[]; total: number }>;
    /** Get published interface (runtime, cached) */
    getPublished(name: string): Promise<Record<string, unknown>>;
  };
}

---

完整产出物清单

#	文件	层	描述	工作量
1	packages/spec/src/ui/interface-lifecycle.zod.ts	Schema	生命周期状态、版本快照、Draft State、请求/响应 Schema	1 周
2	packages/spec/src/ui/interface-lifecycle.test.ts	Schema	全部 Schema 的 Zod 解析测试	3 天
3	packages/spec/src/contracts/interface-lifecycle-service.ts	Contract	IInterfaceLifecycleService 接口定义	3 天
4	packages/spec/src/contracts/interface-lifecycle-service.test.ts	Contract	合约类型测试（参照 deploy-pipeline-service.test.ts）	2 天
5	packages/spec/src/api/interface-lifecycle-api.zod.ts	API	REST 端点注册定义	2 天
6	protocol.zod.ts 扩展	API	ObjectStackProtocol 接口添加新方法	1 天
7	plugin-rest-api.zod.ts 扩展	API	注册 Interface Lifecycle 路由组	1 天
8	packages/client/ 扩展	Client	client.interfaces.* 方法	1 周
9	packages/runtime/ 扩展	Runtime	HttpDispatcher 路由 + Service 实现	2 周
10	packages/metadata/ 扩展	Runtime	注册 interface_draft, interface_version 类型	3 天
11	API_IMPLEMENTATION_PLAN.md 更新	Docs	端点映射表补充	1 天
12	content/docs/ 文档	Docs	新协议参考文档 + 用户指南	3 天

总工作量: ~5-6 周（spec 协议 + runtime 服务 + client SDK）

与上一次评估的工作量合并

范围	内容	工作量
Spec 协议 (1-7)	Schema + Contract + API 定义	2.5 周
Runtime 实现 (8-10)	Client SDK + HttpDispatcher + Service	3 周
ObjectUI 前端 (上次评估)	Designer Store + Auto-save + Publish UI + Builder Canvas	12-16 周
文档 (11-12)	协议参考 + 实现指南	1 周

是否需要我直接在 objectstack-ai/spec 和/或 objectstack-ai/objectui 中创建跟踪 Issue？