protocol.test.ts

import { describe, it, expect } from 'vitest';
import { 
  GetDataRequestSchema, 
  GetDataResponseSchema,
  FindDataRequestSchema,
  FindDataResponseSchema,
  HttpFindQueryParamsSchema,
  CreateDataRequestSchema,
  CreateDataResponseSchema,
  UpdateDataRequestSchema,
  DeleteDataResponseSchema,
  BatchDataRequestSchema,
  CreateManyDataResponseSchema,
  UpdateManyDataRequestSchema,
  DeleteManyDataRequestSchema,
  // View-management schemas removed with the retired ViewProtocol (commit f549a0d4a, v17)
  // Permissions
  CheckPermissionRequestSchema,
  CheckPermissionResponseSchema,
  GetObjectPermissionsRequestSchema,
  GetObjectPermissionsResponseSchema,
  GetEffectivePermissionsResponseSchema,
  // Workflow schemas removed with the retired slot (#4451, v17)
  // Realtime
  RealtimeConnectRequestSchema,
  RealtimeConnectResponseSchema,
  RealtimeSubscribeRequestSchema,
  RealtimeSubscribeResponseSchema,
  SetPresenceRequestSchema,
  GetPresenceResponseSchema,
  // Notifications
  RegisterDeviceRequestSchema,
  RegisterDeviceResponseSchema,
  NotificationPreferencesSchema,
  NotificationSchema,
  ListNotificationsRequestSchema,
  ListNotificationsResponseSchema,
  MarkNotificationsReadRequestSchema,
  // AI
  AiChatRequestSchema,
  AiAgentsResponseSchema,
  AiAgentChatRequestSchema,
  ListAiPendingActionsRequestSchema,
  ListAiPendingActionsResponseSchema,
  ApproveAiPendingActionResponseSchema,
  RejectAiPendingActionResponseSchema,
  AiChatResponseSchema,
  AiCompleteRequestSchema,
  AiModelsResponseSchema,
  CreateAiConversationRequestSchema,
  ListAiConversationsRequestSchema,
  ListAiConversationsResponseSchema,
  UpdateAiConversationRequestSchema,
  // i18n
  GetLocalesResponseSchema,
  GetTranslationsRequestSchema,
  GetTranslationsResponseSchema,
  GetFieldLabelsRequestSchema,
  GetFieldLabelsResponseSchema,
} from './protocol.zod';
import type { ListNotificationsRequest } from './protocol.zod';
import { expectTypeOf } from 'vitest';
import type {
  MetadataProtocol,
  GetMetaItemLayeredRequest,
  GetMetaItemLayeredResponse,
  PublishMetaItemRequest,
  PublishMetaItemResponse,
} from './protocol.zod';

describe('ObjectStack Protocol', () => {

  it('validates GetData', () => {
    const request = {
      object: 'project',
      id: 'p1'
    };
    expect(GetDataRequestSchema.safeParse(request).success).toBe(true);

    const response = {
      object: 'project',
      id: 'p1',
      record: { id: 'p1', name: 'Project A' }
    };
    expect(GetDataResponseSchema.safeParse(response).success).toBe(true);
  });

  it('validates FindData', () => {
    const request = {
      object: 'project',
      query: {
        object: 'project',
        where: { status: 'active' }
      }
    };
    expect(FindDataRequestSchema.safeParse(request).success).toBe(true);

    const response = {
      object: 'project',
      records: [
        { id: 'p1', name: 'Project A', status: 'active' }
      ],
      total: 1
    };
    expect(FindDataResponseSchema.safeParse(response).success).toBe(true);
  });

  it('validates CRUD Operations', () => {
    const createReq = {
      object: 'task',
      data: { title: 'New Task' }
    };
    expect(CreateDataRequestSchema.safeParse(createReq).success).toBe(true);

    const createRes = {
        object: 'task',
        id: 't1',
        record: { id: 't1', title: 'New Task' }
    };
    expect(CreateDataResponseSchema.safeParse(createRes).success).toBe(true);

    const updateReq = {
      object: 'task',
      id: 't1',
      data: { status: 'completed' }
    };
    expect(UpdateDataRequestSchema.safeParse(updateReq).success).toBe(true);

    const deleteRes = {
      object: 'task',
      id: 't1',
      success: true
    };
    expect(DeleteDataResponseSchema.safeParse(deleteRes).success).toBe(true);
  });

  it('validates Batch Operations', () => {
    const batchReq = {
      object: 'task',
      request: {
        operation: 'create',
        records: [{ data: { title: 'T1' } }]
      }
    };
    expect(BatchDataRequestSchema.safeParse(batchReq).success).toBe(true);
  });

  it('validates Bulk Operations', () => {
    const createManyRes = {
      object: 'task',
      records: [{ id: 't1' }, { id: 't2' }],
      count: 2
    };
    expect(CreateManyDataResponseSchema.safeParse(createManyRes).success).toBe(true);

    const updateManyReq = {
      object: 'task',
      records: [{ id: 't1', data: { status: 'done' } }],
      options: { atomic: true }
    };
    expect(UpdateManyDataRequestSchema.safeParse(updateManyReq).success).toBe(true);

    const deleteManyReq = {
      object: 'task',
      ids: ['t1', 't2'],
      options: { atomic: false }
    };
    expect(DeleteManyDataRequestSchema.safeParse(deleteManyReq).success).toBe(true);
  });

  it('no longer publishes a viewId-addressed view CRUD surface', async () => {
    // Retired at protocol 17: five methods, ten schemas, zero implementations
    // and zero routes — and already mis-read once as the contract of
    // `GET /ui/view/:object/:type` (#5948). The unit test that stood here
    // asserted the ten shapes parse; the shapes are what was removed, so it is
    // replaced wholesale rather than re-spelled (the retirement playbook's
    // third fixture disposition — an assertion that keeps passing because
    // nothing is produced is not coverage).
    //
    // Reverse verification, direction predicted first: these are
    // `false`-expecting existence checks over a runtime namespace, so restoring
    // any removed limb turns exactly this test red. Plain red, not one of the
    // inverted directions — nothing downstream counts these names.
    const protocol = await import('./protocol.zod');
    for (const name of [
      'ListViewsRequestSchema', 'ListViewsResponseSchema',
      'GetViewRequestSchema', 'GetViewResponseSchema',
      'CreateViewRequestSchema', 'CreateViewResponseSchema',
      'UpdateViewRequestSchema', 'UpdateViewResponseSchema',
      'DeleteViewRequestSchema', 'DeleteViewResponseSchema',
    ]) {
      expect(name in protocol, `${name} must not be exported`).toBe(false);
    }
  });

  it('keeps the two view surfaces that ARE routed', async () => {
    // The point of the removal, asserted positively so a later reader cannot
    // mistake it for "views left the protocol". `getUiView` serves the resolved
    // render-time view; the stored definition travels on the generic metadata
    // methods with `type: 'view'`.
    const protocol = await import('./protocol.zod');
    expect('GetUiViewRequestSchema' in protocol).toBe(true);
    expect('GetUiViewResponseSchema' in protocol).toBe(true);
    expect('GetMetaItemRequestSchema' in protocol).toBe(true);
    expect('SaveMetaItemRequestSchema' in protocol).toBe(true);
  });

  it('validates Permissions operations', () => {
    expect(CheckPermissionRequestSchema.safeParse({
      object: 'account',
      action: 'edit',
      recordId: 'a1',
    }).success).toBe(true);
    expect(CheckPermissionResponseSchema.safeParse({ allowed: false, reason: 'Insufficient privileges' }).success).toBe(true);
    expect(GetObjectPermissionsRequestSchema.safeParse({ object: 'account' }).success).toBe(true);
    expect(GetObjectPermissionsResponseSchema.safeParse({
      object: 'account',
      permissions: { allowCreate: true, allowRead: true, allowEdit: false, allowDelete: false },
      fieldPermissions: { email: { readable: true, editable: false } },
    }).success).toBe(true);
    expect(GetEffectivePermissionsResponseSchema.safeParse({
      objects: { account: { allowRead: true } },
      systemPermissions: ['manage_users', 'view_reports'],
    }).success).toBe(true);
    // #3391: the effective response carries per-object apiOperations.
    const withOps = GetEffectivePermissionsResponseSchema.safeParse({
      objects: { account: { allowRead: true, apiOperations: ['get', 'list', 'export'] } },
      systemPermissions: [],
    });
    expect(withOps.success).toBe(true);
    if (withOps.success) {
      expect((withOps.data.objects.account as any).apiOperations).toEqual(['get', 'list', 'export']);
    }
  });

  // 'validates Workflow operations' removed (#4451, v17): the workflow
  // schemas were deleted with the retired slot — nothing ever implemented
  // the protocol they described.

  it('validates Realtime operations', () => {
    expect(RealtimeConnectRequestSchema.safeParse({
      transport: 'websocket', channels: ['project.updates'], token: 'tok_abc',
    }).success).toBe(true);
    expect(RealtimeConnectResponseSchema.safeParse({
      connectionId: 'conn_1', transport: 'websocket', url: 'wss://rt.example.com',
    }).success).toBe(true);
    expect(RealtimeSubscribeRequestSchema.safeParse({
      channel: 'project.updates', events: ['record.created', 'record.updated'],
    }).success).toBe(true);
    expect(RealtimeSubscribeResponseSchema.safeParse({
      subscriptionId: 'sub_1', channel: 'project.updates',
    }).success).toBe(true);
    expect(SetPresenceRequestSchema.safeParse({
      channel: 'project.updates',
      state: { userId: 'u1', status: 'online', lastSeen: '2024-01-15T10:00:00Z' },
    }).success).toBe(true);
    expect(GetPresenceResponseSchema.safeParse({
      channel: 'project.updates',
      members: [{ userId: 'u1', status: 'online', lastSeen: '2024-01-15T10:00:00Z' }],
    }).success).toBe(true);
  });

  it('validates Notification operations', () => {
    expect(RegisterDeviceRequestSchema.safeParse({
      token: 'fcm_token_xyz', platform: 'android', deviceId: 'dev_1', name: 'Pixel 8',
    }).success).toBe(true);
    expect(RegisterDeviceResponseSchema.safeParse({ deviceId: 'dev_1', success: true }).success).toBe(true);
    expect(NotificationPreferencesSchema.safeParse({
      email: true, push: true, inApp: true, digest: 'daily',
      channels: { alerts: { enabled: true, push: false } },
    }).success).toBe(true);
    expect(NotificationSchema.safeParse({
      id: 'n1', type: 'task_assigned', title: 'New Task', body: 'You were assigned a task',
      read: false, actionUrl: '/tasks/t1', createdAt: '2024-01-15T10:00:00Z',
    }).success).toBe(true);
    expect(ListNotificationsRequestSchema.safeParse({ read: false, limit: 10 }).success).toBe(true);
    expect(ListNotificationsResponseSchema.safeParse({
      notifications: [{ id: 'n1', type: 'info', title: 'Hi', body: 'Hello', read: false, createdAt: '2024-01-15T10:00:00Z' }],
      unreadCount: 1,
    }).success).toBe(true);
    expect(MarkNotificationsReadRequestSchema.safeParse({ ids: ['n1', 'n2'] }).success).toBe(true);
  });

  /**
   * [commit 90bbf2510] `GET /api/v1/notifications` declares no pagination — on either half.
   *
   * Maintainer ruling 2026-08-07 (Option A), ruled jointly with the `unreadCount` fix (commit 17d095413): one
   * capability's two halves are never half-deleted. `cursor` was declared on the
   * request AND the response and honoured on neither, and `limit` declared a
   * `.default(20)` no request path has ever applied (the server windows at 50).
   *
   * Asserted on the SHAPES rather than only through `safeParse`, and that choice
   * is the whole point: both retired keys were `optional`, so every parse was
   * green before the removal and every parse is green after it. A value-level
   * test cannot see this class of defect at all — which is exactly why the
   * family's double-assertion ratchet (#3877 Stage D) was blind to it.
   */
  it('tombstones `cursor` on BOTH halves, with the prescription', () => {
    // BOTH halves or neither — the ruling's "one capability, two halves" clause,
    // asserted rather than trusted. A half-deletion is the specific outcome the
    // maintainer ruled out, so it gets a test rather than a comment.
    for (const [half, schema] of [
      ['request', ListNotificationsRequestSchema],
      ['response', ListNotificationsResponseSchema],
    ] as const) {
      const probe = half === 'request'
        ? { read: false, limit: 10, cursor: 'n_42' }
        : { notifications: [], unreadCount: 0, cursor: 'n_42' };
      const result = schema.safeParse(probe);

      // Refused, not stripped. Neither schema is `.strict()`, so a BARE DELETION
      // would have parsed this cleanly and dropped the key — the silent-strip
      // class (#3733, ADR-0104), i.e. the very defect this issue reports,
      // re-created one layer down. That is why the assertion is on the refusal.
      expect(result.success, `${half} half must refuse a retired \`cursor\``).toBe(false);
      const issue = result.error!.issues.find((i) => i.path.join('.') === 'cursor');
      expect(issue, `${half} half must fault on the \`cursor\` path`).toBeDefined();

      // The message IS the migration doc (retiredKey's contract), so its
      // substance is asserted, not merely its existence: what was removed, that
      // the route is not paginated, and the replacement to reach for.
      expect(issue!.message).toMatch(/`cursor` was removed from GET \/api\/v1\/notifications/);
      expect(issue!.message).toMatch(/not paginated/i);
      expect(issue!.message).toMatch(/limit/);
      expect(issue!.message).toMatch(/declared on the request AND the response/);
    }

    // `tsc` is the first channel retiredKey buys — the input type is `never`.
    // Pinned as a compile-time fact so deleting the tombstone cannot pass as a
    // refactor. @ts-expect-error fails the build if the key becomes writable.
    // @ts-expect-error `cursor` is retired: its input type is `never`.
    const rejectedByTsc: ListNotificationsRequest = { cursor: 'n_42' };
    void rejectedByTsc;

    // The surviving keys, named. `limit` is plainly optional now — parsing an
    // empty query stamps NO number onto it, where it used to stamp 20 that no
    // request path had ever applied. Stated through the parse result so it holds
    // if Zod's internal representation of a default ever moves.
    expect(Object.keys((ListNotificationsRequestSchema as any).shape)).toEqual(['read', 'type', 'limit', 'cursor']);
    const parsedEmpty = ListNotificationsRequestSchema.parse({});
    expect(Object.prototype.hasOwnProperty.call(parsedEmpty, 'limit')).toBe(false);
    expect(ListNotificationsRequestSchema.parse({ limit: 7 }).limit).toBe(7);
    // The response half keeps exactly what commit 17d095413 landed (`unreadCount`), and gains nothing.
    expect(ListNotificationsResponseSchema.safeParse({ notifications: [], unreadCount: 0 }).success).toBe(true);
  });

  /**
   * These replace the `AiNlq*` / `AiSuggest*` / `AiInsights*` cases (#3718).
   * Those parsed cleanly for years against endpoints no repo has ever mounted
   * — a schema is a shape, never evidence that anything serves it. What is
   * asserted here is the shape of the routes `service-ai` really mounts, which
   * `cloud`'s ledger checks against `buildAIRoutes()` itself.
   */
  it('validates AI operations', () => {
    // chat — Vercel `useChat` flat form, and the JSON (stream:false) reply
    expect(AiChatRequestSchema.safeParse({
      messages: [{ role: 'user', content: 'how many open orders?' }],
      system: 'You are a helpful assistant', model: 'gpt-4o-mini', stream: false,
    }).success).toBe(true);
    // v6 `parts` messages carry no `content` at all — the routes accept them
    expect(AiChatRequestSchema.safeParse({
      messages: [{ role: 'assistant', parts: [{ type: 'text', text: 'hi' }] }],
    }).success).toBe(true);
    expect(AiChatRequestSchema.safeParse({ messages: [] }).success, 'the routes 400 an empty message list').toBe(false);
    expect(AiChatResponseSchema.safeParse({
      content: '42 open orders', model: 'gpt-4o-mini',
      usage: { promptTokens: 10, completionTokens: 5, totalTokens: 15 }, conversationId: 'conv_1',
    }).success).toBe(true);

    // complete
    expect(AiCompleteRequestSchema.safeParse({ prompt: 'Summarise:', options: { maxTokens: 64 } }).success).toBe(true);
    expect(AiCompleteRequestSchema.safeParse({}).success).toBe(false);

    // models — both live shapes: the cloud ADR-0028 allowlist and the bare-id fallback
    expect(AiModelsResponseSchema.safeParse({
      models: [{ id: 'gpt-4o-mini', label: 'GPT-4o mini', default: true }], defaultModel: 'gpt-4o-mini',
    }).success).toBe(true);
    expect(AiModelsResponseSchema.safeParse({ models: ['gpt-4o-mini'] }).success).toBe(true);

    // conversations
    expect(CreateAiConversationRequestSchema.safeParse({ title: 'Q3 pipeline', metadata: { source: 'sdk' } }).success).toBe(true);
    expect(ListAiConversationsResponseSchema.safeParse({
      conversations: [{
        id: 'conv_1', messages: [{ role: 'user', content: 'hi' }],
        createdAt: '2026-07-27T10:00:00Z', updatedAt: '2026-07-27T10:00:00Z',
      }],
      hasMore: false,
    }).success).toBe(true);
    expect(UpdateAiConversationRequestSchema.safeParse({ title: 'Renamed' }).success).toBe(true);
    expect(
      UpdateAiConversationRequestSchema.safeParse({}).success,
      'PATCH with neither title nor metadata is a 400 on the wire',
    ).toBe(false);

    // agents — the named-agent surface `objectui` hand-built URLs for (#3718)
    expect(AiAgentsResponseSchema.safeParse({
      agents: [{
        name: 'build', label: 'Builder', role: 'authoring',
        capabilities: { authoring: true, canvas: true, debug: true, resume: true },
      }],
    }).success).toBe(true);
    expect(
      AiAgentsResponseSchema.safeParse({ agents: [] }).success,
      'an access-filtered catalog is legitimately empty for a seat-less caller',
    ).toBe(true);
    expect(
      AiAgentsResponseSchema.safeParse({ agents: [{ name: 'build', label: 'Builder', role: 'authoring' }] }).success,
      'capabilities drive UI affordances — a row without them is not a row this route returns',
    ).toBe(false);
    expect(AiAgentChatRequestSchema.safeParse({
      messages: [{ role: 'user', content: 'add a status field' }],
      context: { appId: 'crm', objectName: 'account' },
    }).success).toBe(true);
    expect(
      AiAgentChatRequestSchema.safeParse({ messages: [] }).success,
      'the agent chat route 400s an empty message list, same as /ai/chat',
    ).toBe(false);

    // pending actions — the HITL queue
    expect(ListAiPendingActionsResponseSchema.safeParse({
      items: [{
        id: 'pa_1', object_name: 'account', action_name: 'update', tool_name: 'record_update',
        tool_input: '{"id":"a_1"}', status: 'pending', proposed_at: '2026-07-27T10:00:00Z',
      }],
      total: 1,
    }).success).toBe(true);
    expect(
      ListAiPendingActionsRequestSchema.safeParse({ status: 'archived' }).success,
      'status is the persisted lifecycle enum, not free text',
    ).toBe(false);
    expect(ListAiPendingActionsRequestSchema.safeParse({ status: 'pending', limit: 20 }).success).toBe(true);
    // Approval and execution are separate outcomes on one 200 response: a tool
    // that fails after approval is `status: 'failed'`, NOT an HTTP error. A
    // caller reading only `res.ok` reports a failed write as a success.
    expect(ApproveAiPendingActionResponseSchema.safeParse({ status: 'executed', result: { id: 'a_1' } }).success).toBe(true);
    expect(ApproveAiPendingActionResponseSchema.safeParse({ status: 'failed', error: 'row locked' }).success).toBe(true);
    expect(
      ApproveAiPendingActionResponseSchema.safeParse({ status: 'rejected' }).success,
      'approve never yields "rejected" — that is the other route',
    ).toBe(false);
    expect(RejectAiPendingActionResponseSchema.safeParse({ status: 'rejected', id: 'pa_1' }).success).toBe(true);
  });

  it('validates i18n operations', () => {
    expect(GetLocalesResponseSchema.safeParse({
      locales: [
        { code: 'en-US', label: 'English (US)', isDefault: true },
        { code: 'es-ES', label: 'Spanish (Spain)' },
      ],
    }).success).toBe(true);
    expect(GetTranslationsRequestSchema.safeParse({ locale: 'en-US' }).success).toBe(true);
    // The request is locale-only. `namespace`/`keys` were declared here but read
    // by no serving surface, so they were trimmed (#3676). Asserting on the
    // PARSED OUTPUT is the point: `safeParse` still succeeds on a payload
    // carrying them (z.object strips unknown keys), so a success-only assertion
    // would keep passing green whether the fields were trimmed or not.
    const trimmed = GetTranslationsRequestSchema.parse({ locale: 'en-US', namespace: 'objects', keys: ['a'] });
    expect(trimmed).toEqual({ locale: 'en-US' });
    expect(GetTranslationsResponseSchema.safeParse({
      locale: 'en-US',
      translations: { objects: { task: { label: 'Task', pluralLabel: 'Tasks' } }, messages: { save: 'Save' } },
    }).success).toBe(true);
    expect(GetFieldLabelsRequestSchema.safeParse({ object: 'task', locale: 'en-US' }).success).toBe(true);
    expect(GetFieldLabelsResponseSchema.safeParse({
      object: 'task', locale: 'en-US',
      labels: { status: { label: 'Status', help: 'Current task status', options: { open: 'Open', closed: 'Closed' } } },
    }).success).toBe(true);
  });

});

// ==========================================
// GetDiscoveryResponseSchema — capabilities
// ==========================================
import { GetDiscoveryResponseSchema } from './protocol.zod';
import { WELL_KNOWN_CAPABILITY_KEYS } from './discovery.zod';

describe('GetDiscoveryResponseSchema (capabilities)', () => {
  /** The full vocabulary as hierarchical descriptors, all off. */
  const allCapabilitiesOff = () =>
    Object.fromEntries(WELL_KNOWN_CAPABILITY_KEYS.map(k => [k, { enabled: false }]));

  it('should accept response with hierarchical capabilities', () => {
    const result = GetDiscoveryResponseSchema.safeParse({
      version: 'v1',
      name: 'ObjectStack API',
      capabilities: {
        ...allCapabilitiesOff(),
        comments: { enabled: true, features: { threaded: true } },
        automation: { enabled: false },
        search: { enabled: true, description: 'Full-text search' },
      },
    });
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data.capabilities?.comments?.enabled).toBe(true);
      expect(result.data.capabilities?.comments?.features?.threaded).toBe(true);
      expect(result.data.capabilities?.automation?.enabled).toBe(false);
    }
  });

  // [#5672] This fixture used to lead with `feed: { enabled: true }` and assert
  // it round-tripped. It did — `capabilities` was an open `z.record`, so a key
  // no producer emits and no consumer reads looked exactly like a real one.
  // That is the phantom the closed vocabulary removes, and it is worth a test
  // of its own rather than a silent deletion.
  it('strips a capability key outside the closed vocabulary', () => {
    const result = GetDiscoveryResponseSchema.safeParse({
      version: 'v1',
      name: 'ObjectStack API',
      capabilities: { ...allCapabilitiesOff(), feed: { enabled: true } },
    });

    // A zod object STRIPS unknown keys rather than failing, so the parse itself
    // stays green — the fact to pin is that `feed` does not survive into the
    // parsed value, i.e. a consumer reading the spec-parsed body can never see
    // it. (The producers' own gates carry the complementary key-set check that
    // makes emitting it an error rather than a silent drop.)
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data.capabilities).not.toHaveProperty('feed');
    }
  });

  it('rejects a capability map that is missing part of the vocabulary (ruled: an absent capability is `enabled: false`, not a missing key)', () => {
    const { comments: _dropped, ...partial } = allCapabilitiesOff();
    const result = GetDiscoveryResponseSchema.safeParse({
      version: 'v1',
      name: 'ObjectStack API',
      capabilities: partial,
    });

    // `.partial()` makes the `capabilities` BLOCK optional at this layer; it
    // does not make the vocabulary inside it optional. Present ⇒ complete.
    expect(result.success).toBe(false);
  });

  it('should accept response without capabilities (optional)', () => {
    const result = GetDiscoveryResponseSchema.safeParse({
      version: 'v1',
      apiName: 'ObjectStack API',
    });
    // Still optional HERE and only here: `GetDiscoveryResponseSchema` is
    // `DiscoverySchema.partial()`, the lenient wire wrapper. The canonical
    // `DiscoverySchema` — the one every producer's conformance gate parses
    // against since #4828 — requires it (#5672).
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data.capabilities).toBeUndefined();
    }
  });

  it('should accept response with apiName for backward compatibility', () => {
    const result = GetDiscoveryResponseSchema.safeParse({
      version: 'v1',
      apiName: 'ObjectStack API',
    });
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data.apiName).toBe('ObjectStack API');
    }
  });

  it('should accept full DiscoverySchema-compatible response', () => {
    const result = GetDiscoveryResponseSchema.safeParse({
      name: 'ObjectStack',
      version: '1.0.0',
      environment: 'development',
      routes: { data: '/api/v1/data', metadata: '/api/v1/meta' },
      locale: { default: 'en', supported: ['en'], timezone: 'UTC' },
      services: {
        data: { enabled: true, status: 'available', route: '/api/v1/data', provider: 'kernel' },
      },
    });
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data.name).toBe('ObjectStack');
      expect(result.data.environment).toBe('development');
    }
  });
});

// ==========================================
// GetDataRequestSchema — select/expand params
// ==========================================

describe('GetDataRequestSchema (select/expand)', () => {
  it('should accept request with select and expand', () => {
    const result = GetDataRequestSchema.safeParse({
      object: 'contact',
      id: 'c1',
      select: ['name', 'email'],
      expand: ['account', 'owner'],
    });
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data.select).toEqual(['name', 'email']);
      expect(result.data.expand).toEqual(['account', 'owner']);
    }
  });

  it('should accept request without select/expand (optional)', () => {
    const result = GetDataRequestSchema.safeParse({
      object: 'contact',
      id: 'c1',
    });
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data.select).toBeUndefined();
      expect(result.data.expand).toBeUndefined();
    }
  });

  it('should strip unknown query parameters via strict parsing', () => {
    const result = GetDataRequestSchema.strict().safeParse({
      object: 'contact',
      id: 'c1',
      select: ['name'],
      // Unknown params that should be rejected by strict mode
      unknownParam: 'should-be-stripped',
    });
    expect(result.success).toBe(false);
  });
});

// ==========================================
// HttpFindQueryParamsSchema — HTTP parameter naming
// ==========================================

describe('HttpFindQueryParamsSchema', () => {
  it('should accept canonical filter (singular) parameter', () => {
    const result = HttpFindQueryParamsSchema.safeParse({
      filter: '{"status":"active"}',
      select: 'name,email',
      top: 10,
    });
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data.filter).toBe('{"status":"active"}');
      expect(result.data.top).toBe(10);
    }
  });

  it('should accept deprecated filters (plural) parameter for backward compat', () => {
    const result = HttpFindQueryParamsSchema.safeParse({
      filters: '{"status":"active"}',
    });
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data.filters).toBe('{"status":"active"}');
    }
  });

  it('should coerce string numbers for top/skip', () => {
    const result = HttpFindQueryParamsSchema.safeParse({
      top: '25',
      skip: '50',
    });
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data.top).toBe(25);
      expect(result.data.skip).toBe(50);
    }
  });

  // [#25269] The page window the list door enforces — not `z.coerce.number()`,
  // which admitted `-1`, `1.5` and a blank `?top=` (as `0`).
  it.each([['top', '-1'], ['top', '1.5'], ['top', ''], ['top', '   '], ['top', 'abc'], ['skip', '-5'], ['skip', 0.5], ['skip', -1]])(
    'refuses %s=%j — not a page window',
    (key, value) => {
      expect(HttpFindQueryParamsSchema.safeParse({ [key]: value }).success).toBe(false);
    },
  );

  it('keeps 0 and the digits a querystring carries as page windows', () => {
    const result = HttpFindQueryParamsSchema.safeParse({ top: '0', skip: ' 5 ' });
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data.top).toBe(0);
      expect(result.data.skip).toBe(5);
    }
  });

  it('should accept sort, orderBy, expand, search, count', () => {
    const result = HttpFindQueryParamsSchema.safeParse({
      sort: 'name asc,created_at desc',
      expand: 'owner,account',
      search: 'John',
      count: true,
    });
    expect(result.success).toBe(true);
  });

  // [#26817] The list door's accept set for `count` and `select` — not
  // `z.coerce.boolean()` (which read `'false'` as `true` and admitted
  // `'maybe'`) and not any string (which admitted a blank projection).
  it.each([['true', true], ['false', false], [true, true], [false, false]])(
    'reads count=%j as %j',
    (value, expected) => {
      const result = HttpFindQueryParamsSchema.safeParse({ count: value });
      expect(result.success).toBe(true);
      if (result.success) expect(result.data.count).toBe(expected);
    },
  );

  it.each(['maybe', '1', '0', '', 'TRUE', 1, null])('refuses count=%j — neither true nor false', (value) => {
    expect(HttpFindQueryParamsSchema.safeParse({ count: value }).success).toBe(false);
  });

  it.each(['', '   ', ',', ' , ,', '\t'])('refuses select=%j — names no field', (value) => {
    expect(HttpFindQueryParamsSchema.safeParse({ select: value }).success).toBe(false);
  });

  it.each(['name', 'name,email', ' name , email ', 'name,,email'])('keeps select=%j — names a field', (value) => {
    const result = HttpFindQueryParamsSchema.safeParse({ select: value });
    expect(result.success).toBe(true);
    if (result.success) expect(result.data.select).toBe(value);
  });

  it('rejects ?distinct — the querystring spelling of the removed query.distinct', () => {
    const result = HttpFindQueryParamsSchema.safeParse({ distinct: true });
    expect(result.success).toBe(false);
    expect(JSON.stringify(result.error?.issues)).toMatch(/query\.distinct.*removed/s);
  });

  it('should accept empty object (all params optional)', () => {
    expect(HttpFindQueryParamsSchema.safeParse({}).success).toBe(true);
  });
});

import { SaveMetaItemResponseSchema } from './protocol.zod';

/**
 * #5745 — `SaveMetaItemResponseSchema` must describe the FULL body the save
 * route returns, not a subset of it.
 *
 * Before this suite the declaration was `{ success, message? }`, so parsing a
 * real response silently DROPPED `version` / `seq` / `state` /
 * `projectionApplied` — `safeParse` stayed green while the data disappeared,
 * which is the worst shape of failure to leave for a consumer. The first case
 * below is the one that was red: it asserts nothing is stripped.
 *
 * Optionality is measured, not assumed (evidence in the PR): the sole producer
 * always emits `version` / `seq` / `state` on its only reachable success
 * return, and emits `projectionApplied` only when an ADR-0094 mutation
 * projector is registered for the type.
 */
describe('SaveMetaItemResponseSchema (declares the full save response)', () => {
  /** A verbatim capture of a real `saveMetaItem` return (repo write path). */
  const realResponse = {
    success: true,
    version: 'sha256:7aad99c8d969efb5067fff275fb3e5be7ec90f9cd610d41709fcddbf8c34b1f0',
    seq: 1,
    state: 'active',
    message: 'Saved customization overlay (org=org_x, state=active) — type=view, name=cases [seq=1]',
  };

  it('round-trips a real response without stripping any field', () => {
    const parsed = SaveMetaItemResponseSchema.parse(realResponse);
    expect(Object.keys(parsed).sort()).toEqual(Object.keys(realResponse).sort());
    expect(parsed).toEqual(realResponse);
  });

  it('carries the ADR-0008 OCC token: version survives parse as the If-Match value', () => {
    const parsed = SaveMetaItemResponseSchema.parse(realResponse);
    expect(parsed.version).toBe(realResponse.version);
  });

  it('keeps seq as an integer and rejects a fractional one', () => {
    expect(SaveMetaItemResponseSchema.parse(realResponse).seq).toBe(1);
    expect(SaveMetaItemResponseSchema.safeParse({ ...realResponse, seq: 1.5 }).success).toBe(false);
  });

  it('accepts both lifecycle states and rejects any other', () => {
    expect(SaveMetaItemResponseSchema.safeParse({ ...realResponse, state: 'draft' }).success).toBe(true);
    expect(SaveMetaItemResponseSchema.safeParse({ ...realResponse, state: 'active' }).success).toBe(true);
    expect(SaveMetaItemResponseSchema.safeParse({ ...realResponse, state: 'published' }).success).toBe(false);
  });

  it('requires version / seq / state — the producer always emits them', () => {
    for (const missing of ['version', 'seq', 'state'] as const) {
      const body: Record<string, unknown> = { ...realResponse };
      delete body[missing];
      expect(
        SaveMetaItemResponseSchema.safeParse(body).success,
        `omitting '${missing}' must fail parse`,
      ).toBe(false);
    }
  });

  it('leaves projectionApplied optional — absent means no projector ran', () => {
    expect(SaveMetaItemResponseSchema.safeParse(realResponse).success).toBe(true);
    const withProjection = SaveMetaItemResponseSchema.parse({
      ...realResponse,
      projectionApplied: { success: false, error: 'boom-from-projector' },
    });
    expect(withProjection.projectionApplied).toEqual({ success: false, error: 'boom-from-projector' });
  });

  it('projectionApplied.success is required once the key is present', () => {
    expect(
      SaveMetaItemResponseSchema.safeParse({ ...realResponse, projectionApplied: { error: 'x' } }).success,
    ).toBe(false);
  });
});

import { PublishMetaItemResponseSchema } from './protocol.zod';

/**
 * #7294 — the same suite one door over, for `POST /meta/:type/:name/publish`.
 *
 * The publish door had NO declaration at all: `PublishMetaItem` appeared
 * nowhere under `packages/spec/src/`, so its `version` — the same ADR-0008 OCC
 * token the save door already declares — rode the wire with no contract behind
 * it, and `PublishMetaItemResponse` could not be named at the type level.
 *
 * Optionality is measured, not assumed (evidence in the PR): the sole producer
 * is `ObjectStackProtocolImplementation.publishMetaItem`, whose single response
 * literal always sets `success` / `version` / `seq`, and attaches each of the
 * three `*Applied` receipts only when the matching side effect ran.
 */
describe('PublishMetaItemResponseSchema (declares the full publish response)', () => {
  /** A verbatim capture of a real `publishMetaItem` return (promotion path). */
  const realResponse = {
    success: true,
    version: 'sha256:7aad99c8d969efb5067fff275fb3e5be7ec90f9cd610d41709fcddbf8c34b1f0',
    seq: 2,
    message: 'Published draft — type=view, name=cases [seq=2]',
  };

  it('round-trips a real response without stripping any field', () => {
    const parsed = PublishMetaItemResponseSchema.parse(realResponse);
    expect(Object.keys(parsed).sort()).toEqual(Object.keys(realResponse).sort());
    expect(parsed).toEqual(realResponse);
  });

  it('carries the ADR-0008 OCC token: version survives parse as the If-Match value', () => {
    expect(PublishMetaItemResponseSchema.parse(realResponse).version).toBe(realResponse.version);
  });

  it('keeps seq as an integer and rejects a fractional one', () => {
    expect(PublishMetaItemResponseSchema.parse(realResponse).seq).toBe(2);
    expect(PublishMetaItemResponseSchema.safeParse({ ...realResponse, seq: 2.5 }).success).toBe(false);
  });

  it('requires success / version / seq — the producer always emits them', () => {
    for (const missing of ['success', 'version', 'seq'] as const) {
      const body: Record<string, unknown> = { ...realResponse };
      delete body[missing];
      expect(
        PublishMetaItemResponseSchema.safeParse(body).success,
        `omitting '${missing}' must fail parse`,
      ).toBe(false);
    }
  });

  it('carries seedApplied — present only when a `seed` was published', () => {
    expect(PublishMetaItemResponseSchema.safeParse(realResponse).success).toBe(true);
    const withSeed = PublishMetaItemResponseSchema.parse({
      ...realResponse,
      seedApplied: { success: true, inserted: 3, updated: 1 },
    });
    expect(withSeed.seedApplied).toEqual({ success: true, inserted: 3, updated: 1 });
    // The loader's per-record failure list is part of the shape, not extra
    // baggage the schema drops on the floor.
    const withErrors = PublishMetaItemResponseSchema.parse({
      ...realResponse,
      seedApplied: { success: false, inserted: 0, updated: 0, errors: [{ row: 1, reason: 'bad ref' }] },
    });
    expect(withErrors.seedApplied?.errors).toHaveLength(1);
  });

  it('seedApplied counters are required integers once the key is present', () => {
    expect(
      PublishMetaItemResponseSchema.safeParse({ ...realResponse, seedApplied: { success: true } }).success,
    ).toBe(false);
    expect(
      PublishMetaItemResponseSchema.safeParse({
        ...realResponse, seedApplied: { success: true, inserted: 1.5, updated: 0 },
      }).success,
    ).toBe(false);
  });

  it('carries materializeApplied — present only when an ADR-0086 P2 materializer is registered', () => {
    const parsed = PublishMetaItemResponseSchema.parse({
      ...realResponse,
      materializeApplied: { success: false, inserted: 0, updated: 0, error: 'boom-from-materializer' },
    });
    expect(parsed.materializeApplied)
      .toEqual({ success: false, inserted: 0, updated: 0, error: 'boom-from-materializer' });
  });

  it('carries projectionApplied — the same ADR-0094 receipt the save door declares', () => {
    const parsed = PublishMetaItemResponseSchema.parse({
      ...realResponse,
      projectionApplied: { success: false, error: 'boom-from-projector' },
    });
    expect(parsed.projectionApplied).toEqual({ success: false, error: 'boom-from-projector' });
    expect(
      PublishMetaItemResponseSchema.safeParse({ ...realResponse, projectionApplied: { error: 'x' } }).success,
    ).toBe(false);
  });

  it('leaves all three receipts optional — absent means that side effect did not run', () => {
    for (const key of ['seedApplied', 'materializeApplied', 'projectionApplied'] as const) {
      expect(realResponse).not.toHaveProperty(key);
    }
    expect(PublishMetaItemResponseSchema.safeParse(realResponse).success).toBe(true);
  });
});

import { DeleteMetaItemResponseSchema } from './protocol.zod';
import type { DeleteMetaItemResponse } from './protocol.zod';

/** Type-level identity helpers for the reachability pins below. */
type EqD< A, B > = (< T >() => T extends A ? 1 : 2) extends (< T >() => T extends B ? 1 : 2) ? true : false;
type AssertD< T extends true > = T;

/**
 * #13155 — the compile-time half, at module scope and EXPORTED.
 *
 * This is the cost the card names, stated as a type fact: `projectionApplied`
 * is the channel a caller reads INSTEAD of trusting the 200, and `seq` is the
 * ordering token the history/audit trail is read by. Undeclared, neither was
 * reachable from a `DeleteMetaItemResponse` without an `as any` — the
 * consumer-side tolerance Prime Directive #12 rejects.
 *
 * These live at module scope rather than inside an `it()` for the reason the
 * sibling read-side file records: an unread alias in a function body is TS6196
 * under `noUnusedLocals`, and a pin no program compiles is a phantom check.
 * `packages/spec` compiles its tests via `tsconfig.test.json`, so reverting the
 * declaration turns these red at `pnpm typecheck`.
 */
export type DeleteSeqIsReachable = AssertD< EqD< DeleteMetaItemResponse['seq'], number | undefined > >;
export type DeleteProjectionIsReachable = AssertD<
  EqD< DeleteMetaItemResponse['projectionApplied'], { success: boolean; error?: string | undefined } | undefined >
>;

/**
 * #13155 — the third verb on the metadata door declares what its branch sends.
 *
 * `save` (#5745, by the #5563 maintainer ruling) and `publish` (#7294) each
 * declare `seq` and `projectionApplied`. `delete/reset` runs the same ADR-0094
 * projector and the same history append and puts the same two keys on the
 * wire, and declared neither — so this is a decision made for one verb and
 * never carried to its sibling, not a fresh question. The first case below is
 * the one that was red: it asserts nothing is stripped.
 *
 * ⚠️ Optionality here DIFFERS from both siblings, and it is measured rather
 * than mirrored: `seq` is REQUIRED on save and publish because each has a
 * single success return that always sets it, while `deleteMetaItem` has FOUR
 * success returns and only one of them appends a history event. The other
 * three — the two "no row to delete" no-ops and the control-plane legacy
 * raw-engine delete (#5264, which writes no history row and emits no watch
 * event) — answer without a `seq`. Declaring it required would make three of
 * the producer's own returns fail their own contract, which is the #5563
 * defect in mirror image.
 */
describe('DeleteMetaItemResponseSchema (carries the declared = returned discipline to the third verb)', () => {
  /**
   * A verbatim capture of a real `deleteMetaItem` return — the repository
   * path's delete-ful branch, the only one of the four that carries `seq`.
   */
  const realResponse = {
    success: true,
    reset: true,
    seq: 3,
    message: 'Customization overlay deleted — view/cases reset to artifact default. [seq=3]',
  };

  it('round-trips a real response without stripping any field', () => {
    const parsed = DeleteMetaItemResponseSchema.parse(realResponse);
    expect(Object.keys(parsed).sort()).toEqual(Object.keys(realResponse).sort());
    expect(parsed).toEqual(realResponse);
  });

  it('keeps seq as an integer and rejects a fractional one', () => {
    expect(DeleteMetaItemResponseSchema.parse(realResponse).seq).toBe(3);
    expect(DeleteMetaItemResponseSchema.safeParse({ ...realResponse, seq: 3.5 }).success).toBe(false);
  });

  it('leaves seq optional — the three branches that append no history event omit it', () => {
    // The repository path's miss: a success/no-op, no history event.
    const noOverlay = {
      success: true,
      reset: false,
      message: 'No customization overlay found for view/cases — already at artifact default.',
    };
    // The legacy raw-engine delete: a row really went away, still no `seq`,
    // and its receipt message carries no `[seq=…]` suffix for that reason.
    const legacyDeleted = {
      success: true,
      reset: true,
      message: 'Customization overlay deleted — view/cases reset to artifact default.',
    };
    for (const body of [noOverlay, legacyDeleted]) {
      const parsed = DeleteMetaItemResponseSchema.parse(body);
      expect(DeleteMetaItemResponseSchema.safeParse(body).success).toBe(true);
      expect(parsed.seq).toBeUndefined();
      // Absence of `seq` must not be readable as "nothing happened" — `reset`
      // is the key that answers that, and it survives on both branches.
      expect(parsed.reset).toBe(body.reset);
    }
  });

  it('requires success — every one of the four returns emits it', () => {
    const body: Record<string, unknown> = { ...realResponse };
    delete body.success;
    expect(DeleteMetaItemResponseSchema.safeParse(body).success).toBe(false);
  });

  it('carries projectionApplied — the same ADR-0094 receipt both siblings declare', () => {
    const parsed = DeleteMetaItemResponseSchema.parse({
      ...realResponse,
      projectionApplied: { success: false, error: 'boom-from-projector' },
    });
    expect(parsed.projectionApplied).toEqual({ success: false, error: 'boom-from-projector' });
    // Best-effort by contract: the projector threw, the delete still
    // succeeded, and the failure is reported here rather than as a non-200 —
    // which is why a caller reads this instead of trusting the 200.
    expect(parsed.success).toBe(true);
  });

  it('projectionApplied.success is required once the key is present', () => {
    expect(
      DeleteMetaItemResponseSchema.safeParse({ ...realResponse, projectionApplied: { error: 'x' } }).success,
    ).toBe(false);
  });

  it('leaves projectionApplied optional — absent means no projector ran', () => {
    expect(realResponse).not.toHaveProperty('projectionApplied');
    expect(DeleteMetaItemResponseSchema.safeParse(realResponse).success).toBe(true);
    expect(DeleteMetaItemResponseSchema.parse(realResponse).projectionApplied).toBeUndefined();
  });

  it('declares neither `version` nor `advisories` — this branch provably sends neither', () => {
    // The mirror is the siblings' SHAPE, not their member list. A delete mints
    // no new content hash (the row is gone, so there is no ADR-0008 OCC token
    // to echo as `If-Match`), and the #4463 authoring gate runs on the two
    // WRITE doors by D1 — a delete submits no body for it to judge. Declaring
    // either would be a contract for bytes no producer emits.
    const parsed = DeleteMetaItemResponseSchema.parse({
      ...realResponse,
      version: 'sha256:0000000000000000000000000000000000000000000000000000000000000000',
      advisories: [],
    }) as Record<string, unknown>;
    expect(parsed).not.toHaveProperty('version');
    expect(parsed).not.toHaveProperty('advisories');
  });
});

import { RuntimeAuthoringIssueSchema } from './protocol.zod';

/**
 * #4717 — `advisories`, the #4463 D3 advisory half, on the save response.
 *
 * The gate runs the shared author-time rule registry over every body going
 * `active` and splits its findings by severity. `error` becomes the 422; the
 * rest are advisory — they do not block the write, and until #4717 they went
 * only to a process-deduped `console.warn`, which is unreachable by exactly the
 * Studio / MCP / AI authors #4463 exists for.
 *
 * ⚠️ This field is CONDITIONAL, and that has a consequence worth stating where
 * the next reader will meet it: the producer-side conformance gate
 * (`packages/objectql/src/save-meta-response-conformance.test.ts`) works by
 * asserting that nothing was stripped, and a key that is absent strips nothing.
 * So it stays green whether or not this declaration exists — measured, not
 * assumed (the PR's R1/R3 rows). The declaration is deliberate rather than
 * test-driven, and these cases are what make it checkable at all.
 */
describe('SaveMetaItemResponseSchema.advisories (advisory findings ride the 2xx response)', () => {
  const realResponse = {
    success: true,
    version: 'sha256:7aad99c8d969efb5067fff275fb3e5be7ec90f9cd610d41709fcddbf8c34b1f0',
    seq: 1,
    state: 'active',
    message: 'Saved flow \'nightly_purge\' (env-wide, state=active) [seq=1]',
  };

  /** A verbatim capture of a real finding — `lintFlowPatterns`, warning tier. */
  const advisory = {
    rule: 'flow-multi-write-unfiltered',
    path: 'flow \'nightly_purge\' · node \'purge\' (delete_record)',
    where: 'flow \'nightly_purge\' · node \'purge\' (delete_record)',
    message: 'declares `multi: true` with no `filter` key — this is a WHOLE-OBJECT write.',
    hint: 'Add a `filter`, or state the whole-object intent explicitly.',
    severity: 'warning' as const,
  };

  it('carries a real advisory through parse without stripping it', () => {
    const parsed = SaveMetaItemResponseSchema.parse({ ...realResponse, advisories: [advisory] });
    expect(parsed.advisories).toEqual([advisory]);
  });

  it('is OPTIONAL — absence means "nothing to report", never "the gate did not run"', () => {
    expect(SaveMetaItemResponseSchema.safeParse(realResponse).success).toBe(true);
    expect(SaveMetaItemResponseSchema.parse(realResponse).advisories).toBeUndefined();
  });

  it('does not fabricate an empty array when the key is absent', () => {
    // The producer omits the key rather than emitting `[]`, so a clean save's
    // response bytes are unchanged. A `.default([])` here would quietly undo
    // that on the consumer side: every caller would see a key the server never
    // sent, and "absent" would stop being distinguishable at all.
    expect('advisories' in SaveMetaItemResponseSchema.parse(realResponse)).toBe(false);
  });

  it('rejects a non-array, so a single issue object cannot masquerade as the list', () => {
    expect(
      SaveMetaItemResponseSchema.safeParse({ ...realResponse, advisories: advisory }).success,
    ).toBe(false);
  });
});

/**
 * #9176 — `advisories` on the PUBLISH response: the same #4463 D3 key, mirrored
 * onto the other write door. The gate runs on both doors by D1 (a draft→active
 * promotion is gated exactly as a direct active save), but until #9176 only the
 * save door reported — the promotion call site received the gate's advisory
 * return and discarded it. Studio's designer takes draft-then-publish on every
 * edit, so the door its authors actually use was the one that said nothing.
 *
 * Same conditional-field caveat as the save door: the producer-side conformance
 * gate (`packages/objectql/src/publish-meta-response-conformance.test.ts`)
 * asserts nothing is stripped, and an absent key strips nothing — so these
 * declaration pins are what make the key checkable at all, in both directions.
 */
describe('PublishMetaItemResponseSchema.advisories (advisory findings ride the 2xx on the publish door too)', () => {
  const realPublishResponse = {
    success: true,
    version: 'sha256:7aad99c8d969efb5067fff275fb3e5be7ec90f9cd610d41709fcddbf8c34b1f0',
    seq: 2,
    message: 'Published draft — type=flow, name=nightly_purge [seq=2]',
  };

  /** A verbatim capture of a real finding — `lintFlowPatterns`, warning tier. */
  const advisory = {
    rule: 'flow-multi-write-unfiltered',
    path: 'flow \'nightly_purge\' · node \'purge\' (delete_record)',
    where: 'flow \'nightly_purge\' · node \'purge\' (delete_record)',
    message: 'declares `multi: true` with no `filter` key — this is a WHOLE-OBJECT write.',
    hint: 'Add a `filter`, or state the whole-object intent explicitly.',
    severity: 'warning' as const,
  };

  it('carries a real advisory through parse without stripping it', () => {
    const parsed = PublishMetaItemResponseSchema.parse({ ...realPublishResponse, advisories: [advisory] });
    expect(parsed.advisories).toEqual([advisory]);
  });

  it('is OPTIONAL — absence means "nothing to report", never "the gate did not run"', () => {
    expect(PublishMetaItemResponseSchema.safeParse(realPublishResponse).success).toBe(true);
    expect(PublishMetaItemResponseSchema.parse(realPublishResponse).advisories).toBeUndefined();
  });

  it('does not fabricate an empty array when the key is absent', () => {
    // The producer omits the key rather than emitting `[]`, so a clean
    // publish's response bytes are unchanged. A `.default([])` here would
    // quietly undo that on the consumer side: every caller would see a key
    // the server never sent, and "absent" would stop being distinguishable.
    expect('advisories' in PublishMetaItemResponseSchema.parse(realPublishResponse)).toBe(false);
  });

  it('rejects a non-array, so a single issue object cannot masquerade as the list', () => {
    expect(
      PublishMetaItemResponseSchema.safeParse({ ...realPublishResponse, advisories: advisory }).success,
    ).toBe(false);
  });

  it('element shape is the ONE declared finding shape — a lossy element is refused, not narrowed', () => {
    // The element schema is `RuntimeAuthoringIssueSchema` by reference, not a
    // local re-declaration — so an element missing a required key fails the
    // whole parse rather than surviving with keys silently dropped. This is
    // what keeps the save door's `advisories[]`, the publish door's, and the
    // 422 `issues[]` one dialect (#4717).
    const partial = { rule: 'x', severity: 'warning' };
    expect(
      PublishMetaItemResponseSchema.safeParse({ ...realPublishResponse, advisories: [partial] }).success,
    ).toBe(false);
  });
});

/**
 * The element shape itself — declared once (#4717) and re-exported by
 * `@objectstack/metadata-protocol` as its `RuntimeAuthoringIssue`, so the 422's
 * `issues[]` and the 2xx's `advisories[]` cannot drift into two dialects.
 */
describe('RuntimeAuthoringIssueSchema (the ONE finding shape)', () => {
  const issue = {
    rule: 'flow-multi-write-unfiltered',
    path: 'flows[0].nodes[1].config.multi',
    where: 'flow "nightly_purge" · node "purge"',
    message: 'unbounded bulk delete',
    hint: 'add a filter',
    severity: 'warning',
  };

  it('accepts a finding with all six keys', () => {
    expect(RuntimeAuthoringIssueSchema.parse(issue)).toEqual(issue);
  });

  it('requires every one of the six — a partial finding is not a finding', () => {
    for (const missing of ['rule', 'path', 'where', 'message', 'hint', 'severity'] as const) {
      const body: Record<string, unknown> = { ...issue };
      delete body[missing];
      expect(
        RuntimeAuthoringIssueSchema.safeParse(body).success,
        `omitting '${missing}' must fail parse`,
      ).toBe(false);
    }
  });

  it('closes severity to the three the gate emits', () => {
    for (const severity of ['error', 'warning', 'info']) {
      expect(RuntimeAuthoringIssueSchema.safeParse({ ...issue, severity }).success).toBe(true);
    }
    expect(RuntimeAuthoringIssueSchema.safeParse({ ...issue, severity: 'advisory' }).success).toBe(false);
    expect(RuntimeAuthoringIssueSchema.safeParse({ ...issue, severity: 'fatal' }).success).toBe(false);
  });
});

import { PublishPackageDraftsResponseSchema } from './protocol.zod';

/**
 * #9406 — the same suite one door over again, for the BATCH publish door
 * `POST /packages/:id/publish-drafts` (Studio's "publish whole app").
 *
 * The batch door sat in exactly the undeclared state the single-item publish
 * door sat in before #7294: its face lived only as an inline TypeScript return
 * type in `@objectstack/metadata-protocol`, so a field added to or dropped
 * from the response could not turn any declared-contract gate red — #9343's
 * discarded advisories were the measured instance.
 *
 * Optionality is measured, not assumed (receipts in the PR): the producer pair
 * is `ObjectStackProtocolImplementation.publishPackageDrafts` (three return
 * sites, all setting the five required keys) plus the REST door's response
 * mutations in `packages/runtime/src/domains/packages.ts` (`seedApplied`
 * back-fill, `unhiddenApps` / `unhideError` / `rebindError`). The producer
 * side is pinned in
 * `packages/objectql/src/publish-package-drafts-response-conformance.test.ts`
 * and the route mutations in
 * `packages/runtime/src/domains/packages-publish-drafts-response-conformance.test.ts`.
 */
describe('PublishPackageDraftsResponseSchema (declares the batch publish response)', () => {
  /** A verbatim-shaped capture of a real `publishPackageDrafts` return (happy path). */
  const realResponse = {
    success: true,
    outcome: 'published',
    publishedCount: 2,
    failedCount: 0,
    published: [
      { type: 'view', name: 'cases', version: 'sha256:7aad99c8d969efb5067fff275fb3e5be7ec90f9cd610d41709fcddbf8c34b1f0' },
      { type: 'flow', name: 'nightly_purge', version: 'sha256:1bad99c8d969efb5067fff275fb3e5be7ec90f9cd610d41709fcddbf8c34b1f1' },
    ],
    failed: [],
    commitId: 'cmt_01HZX3V9K2',
  };

  it('round-trips a real response without stripping any field', () => {
    const parsed = PublishPackageDraftsResponseSchema.parse(realResponse);
    expect(Object.keys(parsed).sort()).toEqual(Object.keys(realResponse).sort());
    expect(parsed).toEqual(realResponse);
  });

  it('requires the six always-emitted keys — every producer return site sets them', () => {
    for (const missing of ['success', 'outcome', 'publishedCount', 'failedCount', 'published', 'failed'] as const) {
      const body: Record<string, unknown> = { ...realResponse };
      delete body[missing];
      expect(
        PublishPackageDraftsResponseSchema.safeParse(body).success,
        `omitting '${missing}' must fail parse`,
      ).toBe(false);
    }
  });

  it('keeps the counters integers and rejects fractional ones', () => {
    expect(PublishPackageDraftsResponseSchema.safeParse({ ...realResponse, publishedCount: 1.5 }).success).toBe(false);
    expect(PublishPackageDraftsResponseSchema.safeParse({ ...realResponse, failedCount: 0.5 }).success).toBe(false);
  });

  it('published[] elements carry the ADR-0008 OCC token: version is required per element', () => {
    const parsed = PublishPackageDraftsResponseSchema.parse(realResponse);
    expect(parsed.published[0]!.version).toBe(realResponse.published[0]!.version);
    const lossy = {
      ...realResponse,
      published: [{ type: 'view', name: 'cases' }],
    };
    expect(PublishPackageDraftsResponseSchema.safeParse(lossy).success).toBe(false);
  });

  it('failed[] carries the refusal shape, code optional — BATCH_ABORTED marks non-causal items', () => {
    const rolledBack = {
      success: false,
      outcome: 'refused',
      publishedCount: 0,
      failedCount: 2,
      published: [],
      failed: [
        { type: 'object', name: 'ticket', error: "[invalid_metadata] object name 'ticket' must carry the package namespace prefix", code: 'PACKAGE_NAMESPACE_PREFIX_REQUIRED' },
        { type: 'view', name: 'cases', error: 'not published — the batch is all-or-nothing (ADR-0067 D2) and object/ticket failed; the transaction rolled back', code: 'BATCH_ABORTED' },
      ],
    };
    const parsed = PublishPackageDraftsResponseSchema.parse(rolledBack);
    expect(parsed.failed).toEqual(rolledBack.failed);
    // `error` is required once an element exists — a failure with no reason
    // is the shape this declaration exists to refuse.
    expect(
      PublishPackageDraftsResponseSchema.safeParse({
        ...rolledBack,
        failed: [{ type: 'object', name: 'ticket' }],
      }).success,
    ).toBe(false);
  });

  it('carries seedApplied — counters optional ONLY for the route-level fallback producer', () => {
    // The in-batch producer (`applySeedBodies`) always emits both counters.
    const inBatch = PublishPackageDraftsResponseSchema.parse({
      ...realResponse,
      seedApplied: { success: true, inserted: 3, updated: 1, errors: [] },
    });
    expect(inBatch.seedApplied).toEqual({ success: true, inserted: 3, updated: 1, errors: [] });
    // The route back-fill's early-failure shape has no counters — measured on
    // `applyPublishedSeeds` ("required services unavailable") and the door's
    // own catch. The wire face is the union, so the counters are optional.
    const routeFallback = PublishPackageDraftsResponseSchema.parse({
      ...realResponse,
      seedApplied: { success: false, error: 'seed apply failed' },
    });
    expect(routeFallback.seedApplied).toEqual({ success: false, error: 'seed apply failed' });
    // `success` stays required either way.
    expect(
      PublishPackageDraftsResponseSchema.safeParse({ ...realResponse, seedApplied: { inserted: 1, updated: 0 } }).success,
    ).toBe(false);
  });

  it('carries materializeApplied with the batch\'s per-item failures[], not the single door\'s scalar error', () => {
    const parsed = PublishPackageDraftsResponseSchema.parse({
      ...realResponse,
      materializeApplied: {
        success: false, inserted: 1, updated: 0,
        failures: [{ type: 'permission', name: 'sales_reps', error: 'materialize failed' }],
      },
    });
    expect(parsed.materializeApplied?.failures).toHaveLength(1);
    // `failures` is REQUIRED once the key is present — the aggregate's whole
    // point is naming WHICH items never went live (an omitted list would
    // read as "none failed" while `success: false` says otherwise).
    expect(
      PublishPackageDraftsResponseSchema.safeParse({
        ...realResponse,
        materializeApplied: { success: true, inserted: 1, updated: 0 },
      }).success,
    ).toBe(false);
  });

  it('probes is opaque BY DECLARATION (ruled: modeled only once a consumer needs a field): any shape passes through unmodified, unstripped', () => {
    // The real `BuildProbeReport` shape of today…
    const report = { issues: [], checked: { seeds: 1, views: 2, widgets: 0, objects: 3 } };
    const parsed = PublishPackageDraftsResponseSchema.parse({ ...realResponse, probes: report });
    expect(parsed.probes).toEqual(report);
    // …and a future shape this contract deliberately does NOT constrain. If a
    // consumer ever needs a field of `probes`, upgrade the declaration on its
    // own card instead of relaxing this pin.
    expect(
      PublishPackageDraftsResponseSchema.safeParse({ ...realResponse, probes: { anything: 'else' } }).success,
    ).toBe(true);
  });

  it('declares the route-attached ADR-0045 receipts: unhiddenApps / unhideError / rebindError', () => {
    const withFlip = PublishPackageDraftsResponseSchema.parse({
      ...realResponse,
      unhiddenApps: ['crm', 'ops'],
    });
    expect(withFlip.unhiddenApps).toEqual(['crm', 'ops']);
    // #5242's split report: the persisted half rides BESIDE the failure.
    const partWay = PublishPackageDraftsResponseSchema.parse({
      ...realResponse,
      unhiddenApps: ['crm'],
      unhideError: 'visibility flip failed',
    });
    expect(partWay.unhiddenApps).toEqual(['crm']);
    expect(partWay.unhideError).toBe('visibility flip failed');
    const withRebind = PublishPackageDraftsResponseSchema.parse({
      ...realResponse,
      rebindError: 'metadata:reloaded announce failed',
    });
    expect(withRebind.rebindError).toBe('metadata:reloaded announce failed');
  });

  it('leaves every conditional key optional — absent means "did not apply", never "failed"', () => {
    const minimal = {
      success: false,
      // The exact no-op shape (#10462) — the response class where every
      // conditional key is naturally absent.
      outcome: 'nothing_to_publish',
      publishedCount: 0,
      failedCount: 0,
      published: [],
      failed: [],
    };
    for (const key of ['seedApplied', 'materializeApplied', 'probes', 'commitId', 'unhiddenApps', 'unhideError', 'rebindError'] as const) {
      expect(minimal).not.toHaveProperty(key);
    }
    expect(PublishPackageDraftsResponseSchema.safeParse(minimal).success).toBe(true);
  });

  it('does not fabricate any key: parse of a lean body adds nothing (byte-stability half)', () => {
    // No `.default()` anywhere — a declaration that invents keys on the
    // consumer side would make "absent" unobservable and change what callers
    // see relative to the wire bytes. The other half of the byte-stability
    // proof (the wire itself is unchanged) lives in the producer-side
    // conformance suites: nothing on the serving path parses this schema.
    const parsed = PublishPackageDraftsResponseSchema.parse(realResponse) as Record<string, unknown>;
    expect(Object.keys(parsed).sort()).toEqual(Object.keys(realResponse).sort());
  });
});

/**
 * #9406 / #9343 — `advisories` on the batch door's `published[]` elements: the
 * same #4463 D3 key the single-item doors carry, riding each element (the
 * maintainer ruled against a parallel top-level map on #9343). Same
 * conditional-field caveat as both siblings: a strip-nothing conformance gate
 * cannot go red for an absent key, so these declaration pins are what make the
 * key checkable in both directions.
 */
describe('PublishPackageDraftsResponseSchema published[].advisories (ruled: advisory findings ride each published element)', () => {
  const base = {
    success: true,
    // #10462 — `outcome` is required on every producer return; this fixture is
    // a successful publish, so 'published' is the invariant-consistent value.
    outcome: 'published',
    publishedCount: 1,
    failedCount: 0,
    failed: [],
    commitId: 'cmt_01HZX3V9K2',
  };

  /** A verbatim capture of a real finding — `lintFlowPatterns`, warning tier. */
  const advisory = {
    rule: 'flow-multi-write-unfiltered',
    path: 'flow \'nightly_purge\' · node \'purge\' (delete_record)',
    where: 'flow \'nightly_purge\' · node \'purge\' (delete_record)',
    message: 'declares `multi: true` with no `filter` key — this is a WHOLE-OBJECT write.',
    hint: 'Add a `filter`, or state the whole-object intent explicitly.',
    severity: 'warning' as const,
  };

  const el = (extra?: Record<string, unknown>) => ({
    type: 'flow', name: 'nightly_purge',
    version: 'sha256:7aad99c8d969efb5067fff275fb3e5be7ec90f9cd610d41709fcddbf8c34b1f0',
    ...(extra ?? {}),
  });

  it('carries a real advisory through parse on its element, unstripped', () => {
    const parsed = PublishPackageDraftsResponseSchema.parse({
      ...base,
      published: [el({ advisories: [advisory] })],
    });
    expect(parsed.published[0]!.advisories).toEqual([advisory]);
  });

  it('is OPTIONAL per element — absence means "nothing to report", never "the gate did not run"', () => {
    const parsed = PublishPackageDraftsResponseSchema.parse({ ...base, published: [el()] });
    expect(parsed.published[0]!.advisories).toBeUndefined();
    expect('advisories' in parsed.published[0]!).toBe(false);
  });

  it('element shape is the ONE declared finding shape — a lossy element is refused, not narrowed', () => {
    // `RuntimeAuthoringIssueSchema` by reference, not a local re-declaration —
    // the save door's advisories[], the single publish door's, this door's,
    // and the 422 issues[] stay one dialect (#4717).
    const partial = { rule: 'x', severity: 'warning' };
    expect(
      PublishPackageDraftsResponseSchema.safeParse({
        ...base,
        published: [el({ advisories: [partial] })],
      }).success,
    ).toBe(false);
  });

  it('rejects a non-array, so a single issue object cannot masquerade as the list', () => {
    expect(
      PublishPackageDraftsResponseSchema.safeParse({
        ...base,
        published: [el({ advisories: advisory })],
      }).success,
    ).toBe(false);
  });
});

/**
 * #10524 — `failed[].issues`, the structured findings behind a causal refusal,
 * declared at last. The producer has emitted this key since #8333
 * (`...(Array.isArray(e?.issues) ? { issues: e.issues } : {})` on the causal
 * element), but the element declared `type`/`name`/`error`/`code` only — so
 * the key rode the wire undeclared, was stripped by every declared parse, and
 * was invisible to the SDK type. Declaring it is step 1 of the card's
 * declare-then-trim: only once the structured channel is declared may `error`
 * shrink to a headline without the per-path detail becoming unreadable to
 * typed consumers.
 */
describe('PublishPackageDraftsResponseSchema failed[].issues (the causal refusal\'s findings)', () => {
  const base = {
    success: false,
    outcome: 'refused',
    publishedCount: 0,
    failedCount: 1,
    published: [],
  };

  /** A verbatim-shaped capture of the #4463 gate's refusal finding. */
  const gateIssue = {
    rule: 'approval-expression-invalid',
    path: 'flows[0].nodes[1].config.approvers[0].value',
    where: 'flow "leave_approval" · node "approve"',
    message: '\'record.owner ==\' does not parse as CEL.',
    hint: 'Complete the comparison, e.g. `record.owner == current.id`.',
    severity: 'error' as const,
  };

  const causal = (extra?: Record<string, unknown>) => ({
    type: 'flow', name: 'leave_approval',
    error: '[invalid_metadata] flow/leave_approval failed author-time validation: '
      + '1 issue — flows[0].nodes[1].config.approvers[0].value [approval-expression-invalid]',
    code: 'INVALID_METADATA',
    ...(extra ?? {}),
  });

  it('carries a causal refusal\'s issues[] through parse, unstripped', () => {
    const parsed = PublishPackageDraftsResponseSchema.parse({
      ...base,
      failed: [causal({ issues: [gateIssue] })],
    });
    expect(parsed.failed[0]!.issues).toEqual([gateIssue]);
  });

  it('is OPTIONAL per element — BATCH_ABORTED siblings and finding-less refusals omit it, and parse fabricates nothing', () => {
    const parsed = PublishPackageDraftsResponseSchema.parse({ ...base, failed: [causal()] });
    expect(parsed.failed[0]!.issues).toBeUndefined();
    expect('issues' in parsed.failed[0]!).toBe(false);
  });

  it('element shape is the ONE declared finding shape — a lossy element is refused, not narrowed', () => {
    // `RuntimeAuthoringIssueSchema` by reference, not a local re-declaration —
    // the 2xx advisories[] channels and the refusal channels stay one dialect
    // (#4717). The card described the shape as `{ path, message }`; the real
    // emitted shape is the six-key issue, and declaring the narrower guess
    // would strip `rule`/`hint` at the parse door — the same silent-loss
    // family this key's declaration closes.
    const partial = { path: 'flows[0]', message: 'broken' };
    expect(
      PublishPackageDraftsResponseSchema.safeParse({
        ...base,
        failed: [causal({ issues: [partial] })],
      }).success,
    ).toBe(false);
  });

  it('rejects a non-array, so a single issue object cannot masquerade as the list', () => {
    expect(
      PublishPackageDraftsResponseSchema.safeParse({
        ...base,
        failed: [causal({ issues: gateIssue })],
      }).success,
    ).toBe(false);
  });
});

/**
 * #10524 — `seedApplied.issues`, the seed-body schema refusal's structured
 * findings. `seedRequestValidationError` (#8443) has attached `issues` to its
 * declared 422 all along, but both catches that surface that refusal onto
 * `seedApplied` kept only the message — so trimming the message to a headline
 * without this channel would have deleted the author's per-key detail from
 * the wire entirely. Element shape is the `zodIssuesToMetadataIssues` entry
 * (`path` / `message` / zod's own `code`), NOT `RuntimeAuthoringIssueSchema`:
 * these findings are minted by a zod parse, not by the authoring-rule
 * registry, and declaring the six-key shape here would refuse every real
 * emission.
 */
describe('PublishPackageDraftsResponseSchema seedApplied.issues (the seed refusal\'s findings)', () => {
  const base = {
    success: true,
    outcome: 'published',
    publishedCount: 1,
    failedCount: 0,
    published: [
      { type: 'seed', name: 'demo_rows', version: 'sha256:7aad99c8d969efb5067fff275fb3e5be7ec90f9cd610d41709fcddbf8c34b1f0' },
    ],
    failed: [],
  };

  /** A verbatim-shaped capture of the loader-request parse refusal. */
  const seedIssue = {
    path: 'seeds.0.mode',
    message: 'Invalid enum value. Expected \'insert\' | \'upsert\' | \'ignore\', received \'not-a-real-mode\'',
    code: 'invalid_enum_value',
  };

  const refusedApply = (issues?: unknown) => ({
    ...base,
    seedApplied: {
      success: false,
      error: '[invalid_metadata] the published seed bodies failed spec validation: '
        + '1 issue — seeds.0.mode [invalid_enum_value]',
      ...(issues !== undefined ? { issues } : {}),
    },
  });

  it('carries the refusal\'s issues[] through parse, unstripped', () => {
    const parsed = PublishPackageDraftsResponseSchema.parse(refusedApply([seedIssue]));
    expect(parsed.seedApplied!.issues).toEqual([seedIssue]);
  });

  it('zod\'s `code` is optional per entry — an entry without one still parses', () => {
    const { code: _dropped, ...noCode } = seedIssue;
    const parsed = PublishPackageDraftsResponseSchema.parse(refusedApply([noCode]));
    expect(parsed.seedApplied!.issues).toEqual([noCode]);
  });

  it('is OPTIONAL — non-validation failures (driver faults, unreadable bodies) omit it, and parse fabricates nothing', () => {
    const parsed = PublishPackageDraftsResponseSchema.parse(refusedApply());
    expect(parsed.seedApplied!.issues).toBeUndefined();
    expect('issues' in parsed.seedApplied!).toBe(false);
  });

  it('rejects a non-array, so a single issue object cannot masquerade as the list', () => {
    expect(
      PublishPackageDraftsResponseSchema.safeParse(refusedApply(seedIssue)).success,
    ).toBe(false);
  });
});

// Deliberately its own import line, matching the file's later blocks: this
// group pins one change (#9726) and reads as one unit.
import {
  GetMetaItemsRequestSchema,
  GetMetaItemRequestSchema,
  GetMetaItemCachedRequestSchema,
  GetMetaItemLayeredRequestSchema,
} from './protocol.zod';

describe('[ADR-0131 D6] meta-read request schemas declare no organizationId (declared = enforced)', () => {
  // Every metadata read is environment → code: the implementation
  // (`@objectstack/metadata-protocol`) reads no organization on any read
  // verb, so the declared shape carries none. These are non-strict objects,
  // so a request still carrying the retired key parses green with the member
  // STRIPPED — absence from the parse OUTPUT is the observable.
  const cases = [
    ['GetMetaItemsRequestSchema', GetMetaItemsRequestSchema, { type: 'object' }],
    ['GetMetaItemRequestSchema', GetMetaItemRequestSchema, { type: 'view', name: 'account_list' }],
    ['GetMetaItemCachedRequestSchema', GetMetaItemCachedRequestSchema, { type: 'view', name: 'account_list' }],
    ['GetMetaItemLayeredRequestSchema', GetMetaItemLayeredRequestSchema, { type: 'view', name: 'account_list' }],
  ] as const;

  it.each(cases)('%s strips a retired organizationId at parse', (_n, schema, base) => {
    const result = schema.safeParse({ ...base, organizationId: 'org_alpha' });
    expect(result.success).toBe(true);
    if (result.success) {
      expect('organizationId' in (result.data as object)).toBe(false);
    }
  });

  it.each(cases)('%s declares no organizationId member', (_n, schema) => {
    expect('organizationId' in (schema as unknown as { shape: object }).shape).toBe(false);
  });

  it('GetMetaItemLayeredRequestSchema mirrors the implementation inline type member for member', () => {
    // `{ type, name, packageId? }` — the exact parameter type of
    // `getMetaItemLayered` in metadata-protocol. packageId scopes the code
    // layer (ADR-0048); nothing else is declared because nothing else is
    // enforced.
    const full = GetMetaItemLayeredRequestSchema.safeParse({
      type: 'view',
      name: 'account_list',
      packageId: 'pkg_crm',
    });
    expect(full.success).toBe(true);
    expect(GetMetaItemLayeredRequestSchema.safeParse({ type: 'view' }).success).toBe(false);
    expect(GetMetaItemLayeredRequestSchema.safeParse({ name: 'account_list' }).success).toBe(false);
  });
});

describe('meta-read request schemas declare the draft-visibility switches (declared = enforced)', () => {
  // Maintainer ruling 2026-08-18 (commit 2a29caa53): declare `previewDrafts` / `state`
  // exactly where the implementation enforces them, and record `environmentId`
  // as transport-level — OUT of the request shape by decision. The
  // implementation's inline parameter types are the measure:
  //   getMetaItems:  { …, previewDrafts?: boolean }            — no `state`
  //   getMetaItem:   { …, state?: 'active'|'draft', previewDrafts?: boolean }
  //   getMetaItemCached / getMetaItemLayered: NEITHER member
  // As in the #9726 block above, accept-pins assert the parsed VALUE: these are
  // non-strict objects, so `success` alone is exactly the silent-strip state
  // this card closes.
  const previewCases = [
    ['GetMetaItemsRequestSchema', GetMetaItemsRequestSchema, { type: 'object' }],
    ['GetMetaItemRequestSchema', GetMetaItemRequestSchema, { type: 'view', name: 'account_list' }],
  ] as const;

  it.each(previewCases)('%s accepts previewDrafts and PRESERVES it through parse', (_n, schema, base) => {
    const result = schema.safeParse({ ...base, previewDrafts: true });
    expect(result.success).toBe(true);
    if (result.success) {
      expect((result.data as { previewDrafts?: boolean }).previewDrafts).toBe(true);
    }
  });

  it.each(previewCases)('%s keeps previewDrafts OPTIONAL — a published-world read stays valid', (_n, schema, base) => {
    const result = schema.safeParse(base);
    expect(result.success).toBe(true);
    if (result.success) {
      expect('previewDrafts' in (result.data as object)).toBe(false);
    }
  });

  it.each(previewCases)('%s rejects a non-boolean previewDrafts — a switch, not a bag', (_n, schema, base) => {
    expect(schema.safeParse({ ...base, previewDrafts: 'true' }).success).toBe(false);
    expect(schema.safeParse({ ...base, previewDrafts: 1 }).success).toBe(false);
  });

  it('GetMetaItemRequestSchema accepts state and PRESERVES it through parse', () => {
    for (const state of ['active', 'draft'] as const) {
      const result = GetMetaItemRequestSchema.safeParse({ type: 'view', name: 'account_list', state });
      expect(result.success).toBe(true);
      if (result.success) {
        expect((result.data as { state?: string }).state).toBe(state);
      }
    }
  });

  it('GetMetaItemRequestSchema keeps state OPTIONAL and refuses values outside the vocabulary', () => {
    const absent = GetMetaItemRequestSchema.safeParse({ type: 'view', name: 'account_list' });
    expect(absent.success).toBe(true);
    if (absent.success) {
      expect('state' in (absent.data as object)).toBe(false);
    }
    // The lifecycle vocabulary is CLOSED: `archived` is not a read state.
    expect(GetMetaItemRequestSchema.safeParse({ type: 'view', name: 'account_list', state: 'archived' }).success).toBe(false);
    expect(GetMetaItemRequestSchema.safeParse({ type: 'view', name: 'account_list', state: true }).success).toBe(false);
  });

  it('getMetaItems declares NO state — the list verb has no strict-draft mode (mirror of the inline type)', () => {
    // Non-strict schema: an undeclared key parses green but is STRIPPED.
    // Stripping is the observable that the member is NOT declared.
    const result = GetMetaItemsRequestSchema.safeParse({ type: 'object', state: 'draft' });
    expect(result.success).toBe(true);
    if (result.success) {
      expect('state' in (result.data as object)).toBe(false);
    }
  });

  it('cached and layered reads declare NEITHER switch — declared only where enforced', () => {
    const cases = [
      [GetMetaItemCachedRequestSchema, { type: 'view', name: 'account_list' }],
      [GetMetaItemLayeredRequestSchema, { type: 'view', name: 'account_list' }],
    ] as const;
    for (const [schema, base] of cases) {
      const result = schema.safeParse({ ...base, previewDrafts: true, state: 'draft' });
      expect(result.success).toBe(true);
      if (result.success) {
        expect('previewDrafts' in (result.data as object)).toBe(false);
        expect('state' in (result.data as object)).toBe(false);
      }
    }
  });
});

describe('environmentId stays OUT of the meta-read request shape — transport-level by decision, not omission', () => {
  // Maintainer ruling 2026-08-18 (commit 2a29caa53): `environmentId` is the
  // TRANSPORT-level multi-kernel routing key. The REST layer resolves the
  // target kernel from it BEFORE the protocol call, the implementation's
  // parameter types never read it off the request, and these schemas record
  // the same exclusion. This pin is the regression guard for that decision:
  // if someone declares the member, the parse below stops stripping it and
  // this test names the ruling they are overturning.
  const cases = [
    ['GetMetaItemsRequestSchema', GetMetaItemsRequestSchema, { type: 'object' }],
    ['GetMetaItemRequestSchema', GetMetaItemRequestSchema, { type: 'view', name: 'account_list' }],
    ['GetMetaItemCachedRequestSchema', GetMetaItemCachedRequestSchema, { type: 'view', name: 'account_list' }],
    ['GetMetaItemLayeredRequestSchema', GetMetaItemLayeredRequestSchema, { type: 'view', name: 'account_list' }],
  ] as const;

  it.each(cases)('%s does not declare environmentId — a carried value is stripped by parse', (_n, schema, base) => {
    const result = schema.safeParse({ ...base, environmentId: 'env_alpha' });
    expect(result.success).toBe(true);
    if (result.success) {
      expect('environmentId' in (result.data as object)).toBe(false);
    }
  });

  it.each(cases)('%s has no environmentId in its declared shape', (_n, schema) => {
    // Shape-level twin of the strip-pin above: `.shape` enumerates exactly the
    // DECLARED members, so this fails even if stripping semantics ever change.
    const shape = (schema as unknown as { shape: Record<string, unknown> }).shape;
    expect(Object.keys(shape)).not.toContain('environmentId');
  });
});

describe('MetadataProtocol declares getMetaItemLayered', () => {
  // Type-level pins (compiled by the spec test typecheck, the
  // translation-typegen.test.ts pattern). The member is an interface
  // declaration with no runtime shadow, so its presence and shape are only
  // observable to tsc — these pins are what turns red if the member is
  // dropped again or drifts off the layered schemas.

  it('declares the member optional, against the layered request/response schemas', () => {
    // Optional like its `getMetaItemCached` / `deleteMetaItem` siblings:
    // additive to a shipped contract, implementation predating declaration.
    expectTypeOf<MetadataProtocol['getMetaItemLayered']>().toEqualTypeOf<
      ((request: GetMetaItemLayeredRequest) => Promise<GetMetaItemLayeredResponse>) | undefined
    >();
  });

  it("keeps the layered lockSource vocabulary closed — no 'overlay' arm", () => {
    // The drift this card closed: the implementation's inline annotation
    // carried an 'overlay' arm no producer on the layered read path can emit
    // (the only `lockSource: 'overlay'` producer is `getEffectiveLock`, a
    // write/delete-door helper). The declared wire enum stays
    // artifact | package | env-forced; widening it without a producer is the
    // declared-but-unenforced direction Prime Directive #10 forbids.
    expectTypeOf<GetMetaItemLayeredResponse['lockSource']>().toEqualTypeOf<
      'artifact' | 'package' | 'env-forced' | undefined
    >();
  });
});

import { PublishMetaItemRequestSchema } from './protocol.zod';

describe('PublishMetaItemRequestSchema mirrors the implementation parameter type', () => {
  // #7294 declared the RESPONSE side of `POST /meta/:type/:name/publish`; the
  // request shape stayed undeclared — the half-declared door. Maintainer
  // ruling 2026-08-22 (option B): declare the request and the interface
  // member. The measure is the implementation's parameter type in
  // `@objectstack/metadata-protocol` — `{ type, name, actor?, message?,
  // packageId? }` — and the REST door's actual reads;
  // nothing else is declared because nothing else is enforced.
  // As in the #9726 / commit 2a29caa53 blocks above, accept-pins assert the parsed VALUE:
  // this is a non-strict object, so `success` alone is exactly the
  // silent-strip state this family of cards closes.

  const base = { type: 'view', name: 'account_list' } as const;

  it('accepts the full request and PRESERVES every member through parse', () => {
    const full = {
      ...base,
      actor: 'admin',
      message: 'publish from designer',
      packageId: 'pkg_crm',
    };
    const result = PublishMetaItemRequestSchema.safeParse(full);
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data).toEqual(full);
    }
  });

  it('requires type AND name — the promotion addresses one item', () => {
    expect(PublishMetaItemRequestSchema.safeParse(base).success).toBe(true);
    expect(PublishMetaItemRequestSchema.safeParse({ type: 'view' }).success).toBe(false);
    expect(PublishMetaItemRequestSchema.safeParse({ name: 'account_list' }).success).toBe(false);
  });

  it('packageId accepts null AND preserves it apart from absent — the unbound-row pin', () => {
    // `null` pins the lookup to the package-UNBOUND row; an ABSENT key means
    // "match any package". Two different resolutions, so the parse must keep
    // them distinguishable.
    const withNull = PublishMetaItemRequestSchema.safeParse({ ...base, packageId: null });
    expect(withNull.success).toBe(true);
    if (withNull.success) {
      expect('packageId' in (withNull.data as object)).toBe(true);
      expect((withNull.data as { packageId?: string | null }).packageId).toBeNull();
    }
    const absent = PublishMetaItemRequestSchema.safeParse(base);
    expect(absent.success).toBe(true);
    if (absent.success) {
      expect('packageId' in (absent.data as object)).toBe(false);
    }
    expect(PublishMetaItemRequestSchema.safeParse({ ...base, packageId: 42 }).success).toBe(false);
  });

  it('[ADR-0131 D6] a retired organizationId is STRIPPED at parse — the protocol, not the schema, refuses it', () => {
    // The schema is not `.strict()`: the key retired with the per-organization
    // overlay axis is dropped at parse, and an organization-scoped write is
    // refused 403 NOT_OVERRIDABLE by the protocol itself (its identity pin,
    // `protocol.org-scoped-write-refused.test.ts` in @objectstack/metadata-protocol).
    const result = PublishMetaItemRequestSchema.safeParse({ ...base, organizationId: 'org_alpha' });
    expect(result.success).toBe(true);
    if (result.success) {
      expect('organizationId' in (result.data as object)).toBe(false);
    }
  });

  it('the two optional strings stay optional and reject non-strings — values, not bags', () => {
    for (const key of ['actor', 'message'] as const) {
      const absent = PublishMetaItemRequestSchema.safeParse(base);
      expect(absent.success).toBe(true);
      if (absent.success) {
        expect(key in (absent.data as object)).toBe(false);
      }
      expect(PublishMetaItemRequestSchema.safeParse({ ...base, [key]: 42 }).success).toBe(false);
      expect(PublishMetaItemRequestSchema.safeParse({ ...base, [key]: { v: 'x' } }).success).toBe(false);
    }
  });

  it('does not declare environmentId — transport-level by ruling, stripped and shape-absent', () => {
    // Same regression guard as the meta-read block above: if someone declares
    // the member, the parse stops stripping it and this test names the ruling
    // they are overturning (2026-08-18, commit 2a29caa53: `environmentId` is the
    // multi-kernel ROUTING key; `packages/rest` layers it on top via
    // `TransportScopedMetaRequest`).
    const result = PublishMetaItemRequestSchema.safeParse({ ...base, environmentId: 'env_alpha' });
    expect(result.success).toBe(true);
    if (result.success) {
      expect('environmentId' in (result.data as object)).toBe(false);
    }
    const shape = (PublishMetaItemRequestSchema as unknown as { shape: Record<string, unknown> }).shape;
    expect(Object.keys(shape)).not.toContain('environmentId');
  });

  it('does not declare _skipSeedApply — internal batch coordination, not wire contract', () => {
    const result = PublishMetaItemRequestSchema.safeParse({ ...base, _skipSeedApply: true });
    expect(result.success).toBe(true);
    if (result.success) {
      expect('_skipSeedApply' in (result.data as object)).toBe(false);
    }
    const shape = (PublishMetaItemRequestSchema as unknown as { shape: Record<string, unknown> }).shape;
    expect(Object.keys(shape)).not.toContain('_skipSeedApply');
  });
});

describe('MetadataProtocol declares publishMetaItem', () => {
  // Type-level pins (compiled by the spec test typecheck, the
  // translation-typegen.test.ts pattern — same as the getMetaItemLayered block above, commit 11b779e0f).
  // Before this declaration the cast at the REST call site carried
  // MEMBER-EXISTENCE weight (deleting it answered TS2339, not TS2353), so a
  // request literal there was typed by nothing. These pins are what turns
  // red if the member is dropped again or drifts off the publish schemas.

  it('declares the member optional, against the publish request/response schemas', () => {
    // Optional like its `deleteMetaItem` / `getMetaItemLayered` siblings:
    // additive to a shipped contract, implementation predating declaration.
    expectTypeOf<MetadataProtocol['publishMetaItem']>().toEqualTypeOf<
      ((request: PublishMetaItemRequest) => Promise<PublishMetaItemResponse>) | undefined
    >();
    // `{}` satisfies the member's slot exactly because it is optional — an
    // implementation without the verb still type-checks against the
    // interface. This line is the "implementation without it still
    // type-checks" pin, as a real assignment rather than a matcher.
    const absent: Pick<MetadataProtocol, 'publishMetaItem'> = {};
    expect('publishMetaItem' in absent).toBe(false);
  });

  it('refuses an undeclared key at the member call shape — the package-closure publish-gate class this card exists for', () => {
    // Excess-property check on a fresh literal at the declared parameter
    // type: the compile-time teeth the ruling asked for. Before the
    // declaration any key sailed through the `(p as any)` cast.
    const good: PublishMetaItemRequest = { type: 'view', name: 'account_list', packageId: 'pkg_crm' };
    expect(good.type).toBe('view');
    // @ts-expect-error `environmentId` is transport-level (commit 2a29caa53) — not a declared request member.
    const withEnv: PublishMetaItemRequest = { type: 'view', name: 'account_list', environmentId: 'env_a' };
    expect(withEnv.name).toBe('account_list');
    // @ts-expect-error an undeclared (here: misspelt) key is refused at the call shape.
    const misspelt: PublishMetaItemRequest = { type: 'view', name: 'account_list', packageID: 'pkg_crm' };
    expect(misspelt.name).toBe('account_list');
  });
});

import { AuditMetaItemRequestSchema, AuditMetaItemResponseSchema } from './protocol.zod';
import type { AuditMetaItemRequest, AuditMetaItemResponse } from './protocol.zod';

describe('AuditMetaItemRequestSchema mirrors the implementation parameter type', () => {
  // The audit door was a step BEHIND the half-declared publish door (closed by
  // commit cccbe51bf): NEITHER side was declared, and the REST call site reached the
  // verb through `(p as any)` twice (guard + call). The measure is the
  // implementation's parameter type in `@objectstack/metadata-protocol` —
  // `{ type, name, limit?: number }` (ADR-0131 D6 retired `organizationId`) —
  // and the REST door's actual sends; nothing else is declared because nothing else is
  // enforced. As in the #9726 / commit 2a29caa53 / commit cccbe51bf blocks above,
  // accept-pins assert the parsed VALUE: this is a non-strict object, so
  // `success` alone is exactly the silent-strip state this family of cards closes.

  const base = { type: 'view', name: 'account_list' } as const;

  it('accepts the full request and PRESERVES every member through parse', () => {
    const full = { ...base, limit: 50 };
    const result = AuditMetaItemRequestSchema.safeParse(full);
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data).toEqual(full);
    }
  });

  it('requires type AND name — the trail is per item', () => {
    expect(AuditMetaItemRequestSchema.safeParse(base).success).toBe(true);
    expect(AuditMetaItemRequestSchema.safeParse({ type: 'view' }).success).toBe(false);
    expect(AuditMetaItemRequestSchema.safeParse({ name: 'account_list' }).success).toBe(false);
  });

  it('[ADR-0131 D6] a retired organizationId is STRIPPED at parse — the trail is the environment\'s', () => {
    for (const organizationId of ['org_alpha', null]) {
      const result = AuditMetaItemRequestSchema.safeParse({ ...base, organizationId });
      expect(result.success).toBe(true);
      if (result.success) expect('organizationId' in (result.data as object)).toBe(false);
    }
  });

  it('limit is an optional number — values, not bags', () => {
    expect(AuditMetaItemRequestSchema.safeParse(base).success).toBe(true);
    expect(AuditMetaItemRequestSchema.safeParse({ ...base, limit: '50' }).success).toBe(false);
    // The implementation CLAMPS to [1, 500] rather than refusing, so the
    // schema deliberately declares no bounds — declaring `.max(500)` here
    // would refuse a value the shipped verb accepts (clamped), which is the
    // accept/reject drift a declared-surface catch-up must not introduce.
    const clampedNotRefused = AuditMetaItemRequestSchema.safeParse({ ...base, limit: 9999 });
    expect(clampedNotRefused.success).toBe(true);
  });

  it('does not declare environmentId — transport-level by ruling, stripped and shape-absent', () => {
    // Same regression guard as the meta-read and publish blocks above. On THIS
    // door the exclusion is even stronger than the ruling: #8747 removed
    // `environmentId` from the door's payload entirely (the implementation
    // never read it), so declaring it would resurrect a dead wire member.
    const result = AuditMetaItemRequestSchema.safeParse({ ...base, environmentId: 'env_alpha' });
    expect(result.success).toBe(true);
    if (result.success) {
      expect('environmentId' in (result.data as object)).toBe(false);
    }
    const shape = (AuditMetaItemRequestSchema as unknown as { shape: Record<string, unknown> }).shape;
    expect(Object.keys(shape)).not.toContain('environmentId');
  });
});

describe('AuditMetaItemResponseSchema declares the compliance-trail body', () => {
  /** A verbatim-shaped capture of a real `auditMetaItem` return (one denied save). */
  const realResponse = {
    events: [
      {
        id: 'evt_01',
        occurredAt: '2026-08-25T02:11:09.000Z',
        actor: 'admin@objectos.ai',
        source: 'protocol.saveMetaItem',
        operation: 'save',
        outcome: 'denied',
        // adr0112-ok: D6b — persisted audit column, its own lowercase vocabulary
        code: 'item_locked',
        lockState: 'full',
        lockOverridden: false,
        requestId: null,
        note: null,
      },
    ],
  };

  it('parses the real event shape and PRESERVES every member', () => {
    const result = AuditMetaItemResponseSchema.safeParse(realResponse);
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data).toEqual(realResponse);
    }
  });

  it('the honest-empty answer parses — {events: []} is a declared, legal body', () => {
    // `[]` is the honest MISS shape (clean trail / no `find` on the host
    // engine / unprovisioned table). The capability gap is NOT in this body:
    // a protocol without the verb is refused 501 before the call.
    const result = AuditMetaItemResponseSchema.safeParse({ events: [] });
    expect(result.success).toBe(true);
    if (result.success) {
      expect((result.data as { events: unknown[] }).events).toEqual([]);
    }
  });

  it('keeps the operation and outcome vocabularies closed', () => {
    const bad = (patch: Record<string, unknown>) =>
      AuditMetaItemResponseSchema.safeParse({ events: [{ ...realResponse.events[0], ...patch }] });
    expect(bad({ operation: 'diff' }).success).toBe(false);
    expect(bad({ outcome: 'skipped' }).success).toBe(false);
  });
});

describe('MetadataProtocol declares auditMetaItem', () => {
  // Type-level pins (compiled by the spec test typecheck, the
  // translation-typegen.test.ts pattern — same as the getMetaItemLayered (commit 11b779e0f) and publishMetaItem (commit cccbe51bf) blocks
  // above). Before this declaration the casts at the REST call site carried
  // MEMBER-EXISTENCE weight (TS2339, not TS2353), so the request literal
  // there was typed by nothing. These pins are what turns red if the member
  // is dropped again or drifts off the audit schemas.

  it('declares the member optional, against the audit request/response schemas', () => {
    // Optional like its `deleteMetaItem` / `getMetaItemLayered` siblings:
    // additive to a shipped contract, implementation predating declaration.
    expectTypeOf<MetadataProtocol['auditMetaItem']>().toEqualTypeOf<
      ((request: AuditMetaItemRequest) => Promise<AuditMetaItemResponse>) | undefined
    >();
    // An implementation without the verb still type-checks against the
    // interface — the CONFORMING-deployment half of #9426's 501 refusal.
    const absent: Pick<MetadataProtocol, 'auditMetaItem'> = {};
    expect('auditMetaItem' in absent).toBe(false);
  });

  it('refuses an undeclared key at the member call shape', () => {
    const good: AuditMetaItemRequest = { type: 'view', name: 'account_list', limit: 5 };
    expect(good.type).toBe('view');
    // @ts-expect-error `organizationId` is retired (ADR-0131 D6): no metadata read is organization-scoped.
    const withOrg: AuditMetaItemRequest = { type: 'view', name: 'account_list', organizationId: null };
    expect(withOrg.name).toBe('account_list');
    // @ts-expect-error `environmentId` is transport-level (commit 2a29caa53) — not a declared request member (and #8747 removed it from this door's wire payload entirely).
    const withEnv: AuditMetaItemRequest = { type: 'view', name: 'account_list', environmentId: 'env_a' };
    expect(withEnv.name).toBe('account_list');
    // @ts-expect-error an undeclared (here: misspelt) key is refused at the call shape.
    const misspelt: AuditMetaItemRequest = { type: 'view', name: 'account_list', limits: 50 };
    expect(misspelt.name).toBe('account_list');
  });
});

import { HistoryMetaItemRequestSchema, HistoryMetaItemResponseSchema } from './protocol.zod';
import type { HistoryMetaItemRequest, HistoryMetaItemResponse } from './protocol.zod';

describe('HistoryMetaItemRequestSchema mirrors the implementation parameter type', () => {
  // The history door is the audit door's explicitly named twin
  // (`rest-server.ts` says so at the `Number(...)`-shape comment) and was in
  // exactly the state the audit door left via #11678/PR #12003: NEITHER side
  // declared, the REST call site reaching the verb through `(p as any)` twice
  // (guard + call). The measure is the implementation's parameter type in
  // `@objectstack/metadata-protocol` —
  // `{ type, name, sinceSeq?: number, limit?: number }` (ADR-0131 D6 retired
  // `organizationId`) — and the REST door's actual sends; nothing else is declared because
  // nothing else is enforced. As in the #11678 block above, accept-pins
  // assert the parsed VALUE: this is a non-strict object, so `success` alone
  // is exactly the silent-strip state this family of cards closes.

  const base = { type: 'view', name: 'account_list' } as const;

  it('accepts the full request and PRESERVES every member through parse', () => {
    const full = { ...base, sinceSeq: 3, limit: 50 };
    const result = HistoryMetaItemRequestSchema.safeParse(full);
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data).toEqual(full);
    }
  });

  it('requires type AND name — the change log is per item', () => {
    expect(HistoryMetaItemRequestSchema.safeParse(base).success).toBe(true);
    expect(HistoryMetaItemRequestSchema.safeParse({ type: 'view' }).success).toBe(false);
    expect(HistoryMetaItemRequestSchema.safeParse({ name: 'account_list' }).success).toBe(false);
  });

  it('[ADR-0131 D6] a retired organizationId is STRIPPED at parse — the change log is the environment\'s', () => {
    const withOrg = HistoryMetaItemRequestSchema.safeParse({ ...base, organizationId: 'org_alpha' });
    expect(withOrg.success).toBe(true);
    if (withOrg.success) expect('organizationId' in (withOrg.data as object)).toBe(false);
  });

  it('sinceSeq and limit are optional numbers — values, not bags', () => {
    expect(HistoryMetaItemRequestSchema.safeParse(base).success).toBe(true);
    expect(HistoryMetaItemRequestSchema.safeParse({ ...base, sinceSeq: '3' }).success).toBe(false);
    expect(HistoryMetaItemRequestSchema.safeParse({ ...base, limit: '50' }).success).toBe(false);
    // The implementation forwards `limit` to the repository UNCLAMPED (no
    // [1, 500] clamp here, unlike the audit twin), so the schema deliberately
    // declares no bounds — `.max()` would refuse a value the shipped verb
    // accepts.
    const unclamped = HistoryMetaItemRequestSchema.safeParse({ ...base, limit: 9999 });
    expect(unclamped.success).toBe(true);
  });

  it('does not declare environmentId — transport-level by ruling, stripped and shape-absent', () => {
    // Same regression guard as the audit block above, with one twist the
    // audit twin no longer has: this door STILL spreads `environmentId` into
    // its outgoing payload (dead weight — the implementation never declares
    // or reads it). That wire member rides the door's
    // `TransportScopedMetaRequest` wrapper in `packages/rest`; it must never
    // become a protocol key here.
    const result = HistoryMetaItemRequestSchema.safeParse({ ...base, environmentId: 'env_alpha' });
    expect(result.success).toBe(true);
    if (result.success) {
      expect('environmentId' in (result.data as object)).toBe(false);
    }
    const shape = (HistoryMetaItemRequestSchema as unknown as { shape: Record<string, unknown> }).shape;
    expect(Object.keys(shape)).not.toContain('environmentId');
  });
});

describe('HistoryMetaItemResponseSchema declares the change-log body', () => {
  /**
   * A verbatim-shaped capture of a real `historyMetaItem` return: one update
   * (all optional members present) followed by the delete tombstone
   * (`hash: null`, system actor, the sys-repository's fallback `source`, no
   * `version`/`message` recorded — `rowToEvent` omits both when the row
   * carries neither).
   */
  const realResponse = {
    events: [
      {
        seq: 12,
        op: 'update',
        ref: { org: 'org_alpha', type: 'view', name: 'account_list' },
        hash: 'sha256:6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b',
        parentHash: 'sha256:d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35',
        version: 3,
        actor: 'admin@objectos.ai',
        message: 'tweak columns',
        ts: '2026-08-25T02:11:09.000Z',
        source: 'studio',
      },
      {
        seq: 13,
        op: 'delete',
        ref: { org: 'org_alpha', type: 'view', name: 'account_list' },
        hash: null,
        parentHash: 'sha256:6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b',
        actor: null,
        ts: '2026-08-25T02:12:41.000Z',
        source: 'sys-metadata-repo',
      },
    ],
  };

  it('parses the real event shapes and PRESERVES every member', () => {
    const result = HistoryMetaItemResponseSchema.safeParse(realResponse);
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data).toEqual(realResponse);
    }
  });

  it('the honest-empty answer parses — {events: []} is a declared, legal body', () => {
    // `[]` is the honest answer for a clean change log AND for a non-overlay
    // metadata type (no history by construction — the implementation answers
    // `[]` instead of throwing). The capability gap is NOT in this body: a
    // protocol without the verb is refused 501 before the call.
    const result = HistoryMetaItemResponseSchema.safeParse({ events: [] });
    expect(result.success).toBe(true);
    if (result.success) {
      expect((result.data as { events: unknown[] }).events).toEqual([]);
    }
  });

  it('keeps the op vocabulary closed, and ref.type deliberately open', () => {
    const bad = (patch: Record<string, unknown>) =>
      HistoryMetaItemResponseSchema.safeParse({ events: [{ ...realResponse.events[0], ...patch }] });
    // `op` mirrors the producer's own closed enum (ADR-0008 §2.4)…
    expect(bad({ op: 'save' }).success).toBe(false);
    // …while `ref.type` is a plain string BY INTENT: plugin runtime-create
    // types flow through this door and are registry-absent by design, so the
    // static registry enum would refuse real rows (the schema-level note
    // carries the #12038 1C reasoning).
    const pluginType = bad({ ref: { org: 'org_alpha', type: 'capability', name: 'account_list' } });
    expect(pluginType.success).toBe(true);
  });
});

describe('MetadataProtocol declares historyMetaItem', () => {
  // Type-level pins, same pattern as the #11678 audit block above: before
  // this declaration the casts at the REST call site carried MEMBER-EXISTENCE
  // weight (TS2339, not TS2353), so the request literal there was typed by
  // nothing. These pins are what turns red if the member is dropped again or
  // drifts off the history schemas.

  it('declares the member optional, against the history request/response schemas', () => {
    expectTypeOf<MetadataProtocol['historyMetaItem']>().toEqualTypeOf<
      ((request: HistoryMetaItemRequest) => Promise<HistoryMetaItemResponse>) | undefined
    >();
    // An implementation without the verb still type-checks against the
    // interface — the CONFORMING-deployment half of the door's 501 refusal.
    const absent: Pick<MetadataProtocol, 'historyMetaItem'> = {};
    expect('historyMetaItem' in absent).toBe(false);
  });

  it('refuses an undeclared key at the member call shape', () => {
    const good: HistoryMetaItemRequest = { type: 'view', name: 'account_list', sinceSeq: 3, limit: 50 };
    expect(good.type).toBe('view');
    // @ts-expect-error `environmentId` is transport-level (commit 2a29caa53) — not a declared request member (the REST door's spread of it rides the TransportScopedMetaRequest wrapper, never this shape).
    const withEnv: HistoryMetaItemRequest = { type: 'view', name: 'account_list', environmentId: 'env_a' };
    expect(withEnv.name).toBe('account_list');
    // @ts-expect-error an undeclared (here: misspelt) key is refused at the call shape.
    const misspelt: HistoryMetaItemRequest = { type: 'view', name: 'account_list', sinceSeqs: 3 };
    expect(misspelt.name).toBe('account_list');
  });
});

import { DeleteMetaItemRequestSchema } from './protocol.zod';
// `DeleteMetaItemResponse` is imported once, above, beside the response-side
// suite that pins its two #13155 keys — the member pin below reads it from
// there rather than re-importing the same binding.
import type { DeleteMetaItemRequest } from './protocol.zod';

describe('DeleteMetaItemRequestSchema declares the contract members the reset door sends', () => {
  // The sharper sibling of the audit door: the MEMBER was declared all along
  // (so a scan for undeclared members walked past it), while the request
  // schema declared 2 of the 8 members `DELETE /meta/:type/:name` sends —
  // which is why the call-site cast could not come off (TS2353 on six keys,
  // the opposite half of the publish door's TS2339). The measure is the
  // implementation's parameter type in `@objectstack/metadata-protocol` —
  // `{ type, name, parentVersion?, actor?, state?, dropStorage? }` — and the REST door's actual sends. As in the sibling
  // blocks above, accept-pins assert the parsed VALUE: this is a non-strict
  // object, so `success` alone is exactly the silent-strip state this family
  // of cards closes.

  const base = { type: 'view', name: 'account_list' } as const;

  it('accepts the full request and PRESERVES every member through parse', () => {
    const full = {
      ...base,
      parentVersion: 'sha256:abc123',
      actor: 'admin@objectos.ai',
      state: 'draft',
      dropStorage: true,
      packageId: 'com.acme.crm',
    };
    const result = DeleteMetaItemRequestSchema.safeParse(full);
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data).toEqual(full);
    }
  });

  it('[ADR-0048] packageId names the row the delete removes; null names no package, as on the save', () => {
    for (const packageId of ['com.acme.crm', null] as const) {
      const result = DeleteMetaItemRequestSchema.safeParse({ ...base, packageId });
      expect(result.success).toBe(true);
      if (result.success) expect(result.data.packageId).toBe(packageId);
    }
    expect(DeleteMetaItemRequestSchema.safeParse({ ...base, packageId: 42 }).success).toBe(false);
  });

  it('requires type AND name — the reset addresses one item', () => {
    expect(DeleteMetaItemRequestSchema.safeParse(base).success).toBe(true);
    expect(DeleteMetaItemRequestSchema.safeParse({ type: 'view' }).success).toBe(false);
    expect(DeleteMetaItemRequestSchema.safeParse({ name: 'account_list' }).success).toBe(false);
  });

  it('[ADR-0131 D6] a retired organizationId is STRIPPED at parse — the protocol, not the schema, refuses it', () => {
    // The schema is not `.strict()`: the key retired with the per-organization
    // overlay axis is dropped at parse, and an organization-scoped write is
    // refused 403 NOT_OVERRIDABLE by the protocol itself (its identity pin,
    // `protocol.org-scoped-write-refused.test.ts` in @objectstack/metadata-protocol).
    const result = DeleteMetaItemRequestSchema.safeParse({ ...base, organizationId: 'org_alpha' });
    expect(result.success).toBe(true);
    if (result.success) {
      expect('organizationId' in (result.data as object)).toBe(false);
    }
  });

  it('the two optional strings stay optional and reject non-strings — values, not bags', () => {
    for (const key of ['parentVersion', 'actor'] as const) {
      const absent = DeleteMetaItemRequestSchema.safeParse(base);
      expect(absent.success).toBe(true);
      if (absent.success) {
        expect(key in (absent.data as object)).toBe(false);
      }
      expect(DeleteMetaItemRequestSchema.safeParse({ ...base, [key]: 42 }).success).toBe(false);
      expect(DeleteMetaItemRequestSchema.safeParse({ ...base, [key]: { v: 'x' } }).success).toBe(false);
    }
  });

  it('keeps the state vocabulary closed and dropStorage boolean', () => {
    expect(DeleteMetaItemRequestSchema.safeParse({ ...base, state: 'active' }).success).toBe(true);
    expect(DeleteMetaItemRequestSchema.safeParse({ ...base, state: 'pending' }).success).toBe(false);
    expect(DeleteMetaItemRequestSchema.safeParse({ ...base, dropStorage: false }).success).toBe(true);
    // The REST door only ever SENDS `dropStorage: true` (conditional spread),
    // but the contract member is a boolean, mirroring the implementation.
    expect(DeleteMetaItemRequestSchema.safeParse({ ...base, dropStorage: 'true' }).success).toBe(false);
  });

  it('does not declare environmentId — transport-level by ruling, stripped and shape-absent', () => {
    // Same regression guard as the meta-read, publish and audit blocks above:
    // the reset door DOES spread `environmentId` into its outgoing payload,
    // and that member rides `packages/rest`'s `TransportScopedMetaRequest`
    // envelope — never this schema. If someone declares it, this test names
    // the ruling they are overturning (2026-08-18, commit 2a29caa53).
    const result = DeleteMetaItemRequestSchema.safeParse({ ...base, environmentId: 'env_alpha' });
    expect(result.success).toBe(true);
    if (result.success) {
      expect('environmentId' in (result.data as object)).toBe(false);
    }
    const shape = (DeleteMetaItemRequestSchema as unknown as { shape: Record<string, unknown> }).shape;
    expect(Object.keys(shape)).not.toContain('environmentId');
  });
});

describe('MetadataProtocol.deleteMetaItem types against the caught-up request schema', () => {
  // The member declaration itself predates this card; these pins are the
  // request-shape half — what turns red if the schema drops back to
  // `{ type, name }` (the member would still exist; the door literal would
  // stop compiling) or if a key drifts off the implementation's vocabulary.

  it('declares the member optional, against the delete request/response schemas', () => {
    expectTypeOf<MetadataProtocol['deleteMetaItem']>().toEqualTypeOf<
      ((request: DeleteMetaItemRequest) => Promise<DeleteMetaItemResponse>) | undefined
    >();
    const absent: Pick<MetadataProtocol, 'deleteMetaItem'> = {};
    expect('deleteMetaItem' in absent).toBe(false);
  });

  it('refuses an undeclared key at the member call shape — the TS2353 half this card names', () => {
    const good: DeleteMetaItemRequest = {
      type: 'view',
      name: 'account_list',
      parentVersion: 'sha256:abc123',
      actor: 'admin',
      state: 'draft',
      dropStorage: true,
      packageId: 'com.acme.crm',
    };
    expect(good.type).toBe('view');
    // @ts-expect-error `environmentId` is transport-level (commit 2a29caa53) — not a declared request member; the REST door layers it on via TransportScopedMetaRequest.
    const withEnv: DeleteMetaItemRequest = { type: 'view', name: 'account_list', environmentId: 'env_a' };
    expect(withEnv.name).toBe('account_list');
    // @ts-expect-error `organizationId` is retired (ADR-0131 D6): no metadata write is organization-scoped.
    const withOrg: DeleteMetaItemRequest = { type: 'view', name: 'account_list', organizationId: 'org_alpha' };
    expect(withOrg.name).toBe('account_list');
    // @ts-expect-error an undeclared (here: misspelt) key is refused at the call shape.
    const misspelt: DeleteMetaItemRequest = { type: 'view', name: 'account_list', dropstorage: true };
    expect(misspelt.name).toBe('account_list');
  });
});

import { SaveMetaItemRequestSchema } from './protocol.zod';
import type { SaveMetaItemRequest, SaveMetaItemResponse } from './protocol.zod';

describe('SaveMetaItemRequestSchema declares the contract members the save door sends', () => {
  // The biggest remaining member of the request-shape family the reset twin
  // above belongs to: `saveMetaItem` is a REQUIRED protocol member (so a scan
  // for undeclared members walked past it), while the request schema declared
  // 3 of the ~11 members `PUT /meta/:type/:name` sends — which is why the
  // call-site cast could not come off (TS2353 on every undeclared key, pure
  // request-shape smuggling, never feature detection). The measure is the
  // implementation's parameter type in `@objectstack/metadata-protocol` —
  // `{ type, name, item?, parentVersion?, actor?, force?, mode?, packageId?,
  // source?, writeFace? }` — and the REST door's actual
  // sends. As in the sibling blocks above, accept-pins assert the parsed
  // VALUE: this is a non-strict object, so `success` alone is exactly the
  // silent-strip state this family of cards closes.

  // `item` rides every fixture: the untouched `z.unknown()` member is
  // measured key-REQUIRED at parse (absent key refused; a present `null`
  // parses and is then refused 400 by the implementation's own guard) —
  // pre-existing contract behaviour this card deliberately does not move.
  const base = { type: 'view', name: 'account_list', item: { label: 'Account list' } } as const;

  it('accepts the full request and PRESERVES every member through parse', () => {
    const full = {
      ...base,
      parentVersion: 'sha256:abc123',
      actor: 'admin@objectos.ai',
      force: true,
      mode: 'draft',
      packageId: 'com.example.crm',
      writeFace: 'meta-envelope',
    };
    const result = SaveMetaItemRequestSchema.safeParse(full);
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data).toEqual(full);
    }
  });

  it('requires type AND name — the save addresses one item', () => {
    expect(SaveMetaItemRequestSchema.safeParse(base).success).toBe(true);
    expect(SaveMetaItemRequestSchema.safeParse({ type: 'view', item: {} }).success).toBe(false);
    expect(SaveMetaItemRequestSchema.safeParse({ name: 'account_list', item: {} }).success).toBe(false);
  });

  it('keeps item key-required at parse — the measured pre-existing contract', () => {
    // Absent key is refused at parse; an explicit `null` PARSES (the
    // implementation's own opening guard then refuses it 400) — so the
    // wire-reachable "explicitly null envelope" keeps reaching the guard
    // that owns its error message rather than dying as an anonymous parse
    // failure.
    expect(SaveMetaItemRequestSchema.safeParse({ type: 'view', name: 'account_list' }).success).toBe(false);
    expect(SaveMetaItemRequestSchema.safeParse({ type: 'view', name: 'account_list', item: null }).success).toBe(true);
  });

  it('[ADR-0131 D6] a retired organizationId is STRIPPED at parse — the protocol, not the schema, refuses it', () => {
    // The schema is not `.strict()`: the key retired with the per-organization
    // overlay axis is dropped at parse, and an organization-scoped write is
    // refused 403 NOT_OVERRIDABLE by the protocol itself (its identity pin,
    // `protocol.org-scoped-write-refused.test.ts` in @objectstack/metadata-protocol).
    const result = SaveMetaItemRequestSchema.safeParse({ ...base, organizationId: 'org_alpha' });
    expect(result.success).toBe(true);
    if (result.success) {
      expect('organizationId' in (result.data as object)).toBe(false);
    }
  });

  it('the optional string stays optional and rejects non-strings — a value, not a bag', () => {
    for (const key of ['actor'] as const) {
      const absent = SaveMetaItemRequestSchema.safeParse(base);
      expect(absent.success).toBe(true);
      if (absent.success) {
        expect(key in (absent.data as object)).toBe(false);
      }
      expect(SaveMetaItemRequestSchema.safeParse({ ...base, [key]: 42 }).success).toBe(false);
      expect(SaveMetaItemRequestSchema.safeParse({ ...base, [key]: { v: 'x' } }).success).toBe(false);
    }
  });

  it('parentVersion is the nullable OCC pin — string pins, null is the first-write pin, absent is unpinned', () => {
    // Unlike the reset twin above (plain optional string — its implementation
    // folds a present `null` back to the current hash), the save verb passes
    // `null` through to the repository conflict check unchanged, so the
    // absent-vs-null distinction is a real, enforced contract member here and
    // the schema mirrors the implementation's `string | null`.
    expect(SaveMetaItemRequestSchema.safeParse({ ...base, parentVersion: 'sha256:abc' }).success).toBe(true);
    const withNull = SaveMetaItemRequestSchema.safeParse({ ...base, parentVersion: null });
    expect(withNull.success).toBe(true);
    if (withNull.success) {
      // Preserved as null, never stripped to absent — the two spell
      // different pins.
      expect('parentVersion' in (withNull.data as object)).toBe(true);
      expect((withNull.data as { parentVersion: unknown }).parentVersion).toBeNull();
    }
    expect(SaveMetaItemRequestSchema.safeParse({ ...base, parentVersion: 42 }).success).toBe(false);
  });

  it('keeps force boolean and the mode / writeFace vocabularies closed', () => {
    expect(SaveMetaItemRequestSchema.safeParse({ ...base, force: false }).success).toBe(true);
    // The REST door only ever SENDS `force: true` (conditional spread), but
    // the contract member is a boolean, mirroring the implementation.
    expect(SaveMetaItemRequestSchema.safeParse({ ...base, force: 'true' }).success).toBe(false);
    expect(SaveMetaItemRequestSchema.safeParse({ ...base, mode: 'draft' }).success).toBe(true);
    expect(SaveMetaItemRequestSchema.safeParse({ ...base, mode: 'publish' }).success).toBe(true);
    expect(SaveMetaItemRequestSchema.safeParse({ ...base, mode: 'stage' }).success).toBe(false);
    for (const face of ['package-duplicate', 'meta-envelope', 'meta-dispatch', 'external-import'] as const) {
      expect(SaveMetaItemRequestSchema.safeParse({ ...base, writeFace: face }).success).toBe(true);
    }
    expect(SaveMetaItemRequestSchema.safeParse({ ...base, writeFace: 'rest' }).success).toBe(false);
  });

  it('packageId mirrors the implementation nullable — and null is preserved, not stripped', () => {
    expect(SaveMetaItemRequestSchema.safeParse({ ...base, packageId: 'com.example.crm' }).success).toBe(true);
    const withNull = SaveMetaItemRequestSchema.safeParse({ ...base, packageId: null });
    expect(withNull.success).toBe(true);
    if (withNull.success) {
      expect('packageId' in (withNull.data as object)).toBe(true);
      expect((withNull.data as { packageId: unknown }).packageId).toBeNull();
    }
    expect(SaveMetaItemRequestSchema.safeParse({ ...base, packageId: 42 }).success).toBe(false);
  });

  it('does not declare environmentId — transport-level by ruling, stripped and shape-absent', () => {
    // Same regression guard as the meta-read, publish, audit, history and
    // reset blocks above: the save door DOES spread `environmentId` into its
    // outgoing payload, and that member rides `packages/rest`'s
    // `TransportScopedMetaRequest` envelope — never this schema. If someone
    // declares it, this test names the ruling they are overturning
    // (2026-08-18, commit 2a29caa53).
    const result = SaveMetaItemRequestSchema.safeParse({ ...base, environmentId: 'env_alpha' });
    expect(result.success).toBe(true);
    if (result.success) {
      expect('environmentId' in (result.data as object)).toBe(false);
    }
    const shape = (SaveMetaItemRequestSchema as unknown as { shape: Record<string, unknown> }).shape;
    expect(Object.keys(shape)).not.toContain('environmentId');
  });

  it('does not declare source — implementation-internal provenance with no producer on this contract', () => {
    // The implementation declares `source?: string` (its own
    // `migrateStoredMetadata` call sends 'migrate-stored'), but NO door sends
    // it and the REST layer deliberately never reads a client-supplied
    // provenance — the publish-door precedent (#11426) leaves such a member
    // undeclared until a producer on THIS contract pulls it. Declaring it
    // would advertise a wire-authorable provenance channel that does not
    // exist.
    const result = SaveMetaItemRequestSchema.safeParse({ ...base, source: 'studio' });
    expect(result.success).toBe(true);
    if (result.success) {
      expect('source' in (result.data as object)).toBe(false);
    }
    const shape = (SaveMetaItemRequestSchema as unknown as { shape: Record<string, unknown> }).shape;
    expect(Object.keys(shape)).not.toContain('source');
  });
});

describe('MetadataProtocol.saveMetaItem types against the caught-up request schema', () => {
  // The member declaration itself long predates this card — `saveMetaItem`
  // is REQUIRED on `MetadataProtocol` — so these pins are the request-shape
  // half: what turns red if the schema drops back to `{ type, name, item }`
  // (the member would still exist; the door literal would stop compiling) or
  // if a key drifts off the implementation's vocabulary.

  it('declares the member REQUIRED, against the save request/response schemas', () => {
    expectTypeOf<MetadataProtocol['saveMetaItem']>().toEqualTypeOf<
      (request: SaveMetaItemRequest) => Promise<SaveMetaItemResponse>
    >();
  });

  it('refuses an undeclared key at the member call shape — the TS2353 half this card names', () => {
    const good: SaveMetaItemRequest = {
      type: 'view',
      name: 'account_list',
      item: { label: 'Account list' },
      parentVersion: null,
      actor: 'admin',
      force: true,
      mode: 'draft',
      packageId: null,
      writeFace: 'meta-dispatch',
    };
    expect(good.type).toBe('view');
    // @ts-expect-error `environmentId` is transport-level (commit 2a29caa53) — not a declared request member; the REST door layers it on via TransportScopedMetaRequest.
    const withEnv: SaveMetaItemRequest = { type: 'view', name: 'account_list', environmentId: 'env_a' };
    expect(withEnv.name).toBe('account_list');
    // @ts-expect-error `organizationId` is retired (ADR-0131 D6): no metadata write is organization-scoped.
    const withOrg: SaveMetaItemRequest = { type: 'view', name: 'account_list', item: {}, organizationId: 'org_alpha' };
    expect(withOrg.name).toBe('account_list');
    // @ts-expect-error `source` is implementation-internal provenance — no producer on this contract sends it, and the REST layer never reads it off the wire.
    const withSource: SaveMetaItemRequest = { type: 'view', name: 'account_list', source: 'studio' };
    expect(withSource.name).toBe('account_list');
    // @ts-expect-error an undeclared (here: misspelt) key is refused at the call shape.
    const misspelt: SaveMetaItemRequest = { type: 'view', name: 'account_list', writeface: 'meta-envelope' };
    expect(misspelt.name).toBe('account_list');
  });
});

// ==========================================
// Meta history / diagnostics response conformance (#12038)
// ==========================================
//
// The #3877 conformance half of the #12038 bindings — one handwritten,
// verbatim-shaped capture per newly bound schema (the AuditMetaItemResponse
// pattern above), asserting the parse PRESERVES every member and that the
// honest-empty body is a declared, legal answer. The four invented client-test
// mocks the survey flagged (§3b) are NOT reused here — none of them described
// a shape these routes ever answered.

import {
  GetPublishedMetaItemResponseSchema,
  ListDraftsResponseSchema,
  GetMetaDiagnosticsResponseSchema,
  FindReferencesToMetaResponseSchema,
  RollbackMetaItemResponseSchema,
  DiffMetaItemResponseSchema,
} from './protocol.zod';

describe('ListDraftsResponseSchema declares the pending-drafts body', () => {
  /**
   * A verbatim-shaped capture of a real `listDrafts` return: a plain-string
   * label, an inline-locale-map label (the `I18nLabel` form the UI types
   * author), and a draft whose body declares no label at all.
   */
  const realResponse = {
    drafts: [
      {
        type: 'view',
        name: 'account_pipeline',
        label: 'Account Pipeline',
        packageId: 'com.example.crm',
        updatedAt: '2026-08-27T09:12:44.000Z',
        updatedBy: 'admin@objectos.ai',
      },
      {
        type: 'app',
        name: 'field_service',
        label: { en: 'Field Service', 'zh-CN': '现场服务' },
        packageId: 'com.example.fsm',
        updatedAt: '2026-08-27T09:13:02.000Z',
        updatedBy: 'admin@objectos.ai',
      },
      {
        type: 'object',
        name: 'lead_source',
        label: null,
        packageId: null,
        updatedAt: null,
        updatedBy: null,
      },
    ],
  };

  it('parses the real draft rows and PRESERVES every member', () => {
    const result = ListDraftsResponseSchema.safeParse(realResponse);
    expect(result.success).toBe(true);
    if (result.success) expect(result.data).toEqual(realResponse);
  });

  it('a draft whose body declares no label reads `null` — never the item name standing in for it', () => {
    const result = ListDraftsResponseSchema.safeParse(realResponse);
    expect(result.success).toBe(true);
    if (!result.success) return;
    const unlabelled = result.data.drafts.find((d) => d.name === 'lead_source');
    expect(unlabelled?.label).toBeNull();
  });

  it('`label` is required on the wire: a row that omits it is refused at the member', () => {
    const { label: _omitted, ...withoutLabel } = realResponse.drafts[2]!;
    const result = ListDraftsResponseSchema.safeParse({ drafts: [withoutLabel] });
    expect(result.success).toBe(false);
    if (!result.success) {
      expect(result.error.issues.map((i) => i.path.join('.'))).toContain('drafts.0.label');
    }
  });

  it('the honest-empty answer parses — {drafts: []} is a declared, legal body', () => {
    expect(ListDraftsResponseSchema.safeParse({ drafts: [] }).success).toBe(true);
  });

  it('[#23073] two languages of one email_template are two drafts told apart by `member`, which the parse keeps', () => {
    const draft = (member: string) => ({
      type: 'email_template',
      name: 'acme.welcome',
      member,
      label: 'Welcome',
      packageId: 'com.acme.mail',
      updatedAt: '2026-10-12T09:00:00.000Z',
      updatedBy: 'admin@objectos.ai',
    });
    const bundle = { drafts: [draft('en-US'), draft('zh-CN'), realResponse.drafts[0]!] };
    const result = ListDraftsResponseSchema.safeParse(bundle);
    expect(result.success).toBe(true);
    if (!result.success) return;
    expect(result.data).toEqual(bundle);
    expect(result.data.drafts.map((d) => d.member)).toEqual(['en-US', 'zh-CN', undefined]);
    // A type whose identity is its name alone carries no `member` key at all.
    expect(result.data.drafts[2]).not.toHaveProperty('member');
  });
});

describe('GetMetaDiagnosticsResponseSchema declares the validation-sweep body', () => {
  /** A verbatim-shaped capture of a real `getMetaDiagnostics` return (one failing view). */
  const realResponse = {
    entries: [
      {
        type: 'view',
        name: 'broken_pipeline',
        diagnostics: {
          valid: false,
          errors: [{ path: 'columns.0.field', message: 'Unknown field: statuss', code: 'invalid_field' }],
          warnings: [{ path: 'filters', message: 'Empty filter group' }],
        },
      },
    ],
    total: 1,
    scannedTypes: 12,
    scannedItems: 184,
    stats: {
      view: { count: 42, locked: 3, packages: ['com.example.crm'] },
      object: { count: 17, locked: 0, packages: ['com.example.crm', 'com.example.docs'] },
    },
  };

  it('parses the real sweep shape and PRESERVES every member', () => {
    const result = GetMetaDiagnosticsResponseSchema.safeParse(realResponse);
    expect(result.success).toBe(true);
    if (result.success) expect(result.data).toEqual(realResponse);
  });

  it('the honest-empty sweep parses — no failing entries is a declared, legal body', () => {
    const empty = { entries: [], total: 0, scannedTypes: 0, scannedItems: 0, stats: {} };
    expect(GetMetaDiagnosticsResponseSchema.safeParse(empty).success).toBe(true);
  });
});

describe('FindReferencesToMetaResponseSchema declares the reverse-references body', () => {
  /** A verbatim-shaped capture of a real `findReferencesToMeta` return. */
  const realResponse = {
    references: [
      { type: 'view', name: 'account_list', label: 'Accounts', path: 'columns.2.field', kind: 'field' },
      { type: 'flow', name: 'lead_convert', path: 'nodes.3.object', kind: 'object' },
    ],
  };

  it('parses the real reference rows and PRESERVES every member', () => {
    const result = FindReferencesToMetaResponseSchema.safeParse(realResponse);
    expect(result.success).toBe(true);
    if (result.success) expect(result.data).toEqual(realResponse);
  });

  it('the honest-empty answer parses — {references: []} is the declared answer on kernels without reference tracking', () => {
    expect(FindReferencesToMetaResponseSchema.safeParse({ references: [] }).success).toBe(true);
  });
});

describe('RollbackMetaItemResponseSchema declares the item-rollback body', () => {
  /** A verbatim-shaped capture of a real `rollbackMetaItem` return. */
  const realResponse = {
    success: true,
    version: 'W/"7"',
    seq: 7,
    restoredFromVersion: 4,
    message: 'Rolled back to version 4',
  };

  it('parses the real rollback receipt and PRESERVES every member', () => {
    const result = RollbackMetaItemResponseSchema.safeParse(realResponse);
    expect(result.success).toBe(true);
    if (result.success) expect(result.data).toEqual(realResponse);
  });

  it('`message` is genuinely optional — the messageless receipt parses', () => {
    const { message: _omitted, ...rest } = realResponse;
    expect(RollbackMetaItemResponseSchema.safeParse(rest).success).toBe(true);
  });
});

describe('DiffMetaItemResponseSchema declares the structural-diff body', () => {
  /** A verbatim-shaped capture of a real `diffMetaItem` return. */
  const realResponse = {
    type: 'object',
    name: 'customer',
    fromVersion: 2,
    toVersion: 5,
    added: [{ path: 'fields.priority', value: { type: 'select', options: ['low', 'high'] } }],
    removed: [{ path: 'fields.legacy_code', value: { type: 'text' } }],
    changed: [{ path: 'label', from: 'Customer', to: 'Account' }],
  };

  it('parses the real diff shape and PRESERVES every member', () => {
    const result = DiffMetaItemResponseSchema.safeParse(realResponse);
    expect(result.success).toBe(true);
    if (result.success) expect(result.data).toEqual(realResponse);
  });

  it('null version sides are declared — a first-version diff parses', () => {
    const firstVersion = { ...realResponse, fromVersion: null, toVersion: null };
    expect(DiffMetaItemResponseSchema.safeParse(firstVersion).success).toBe(true);
  });
});

describe('GetPublishedMetaItemResponseSchema stays opaque (ruled: no shape frozen against the current type registry)', () => {
  it('accepts an arbitrary metadata item body and PRESERVES it — no shape is imposed', () => {
    const itemBody = { name: 'all_leads', type: 'grid', object: 'lead', columns: [{ field: 'name' }] };
    const result = GetPublishedMetaItemResponseSchema.safeParse(itemBody);
    expect(result.success).toBe(true);
    if (result.success) expect(result.data).toEqual(itemBody);
  });

  it('imposes nothing on the body — opacity is the ruled contract, not an accident', () => {
    // The ruling (1C) forbids a discriminated union frozen against today's
    // type registry; `unknown` accepts every body, including non-objects.
    expect(GetPublishedMetaItemResponseSchema.safeParse('raw-string-body').success).toBe(true);
    expect(GetPublishedMetaItemResponseSchema.safeParse(null).success).toBe(true);
  });
});

describe('ListAiConversationsResponseSchema declares the next-page signal', () => {
  // Ruled on #19543: the list is newest first and pages by keyset, `cursor`
  // being the id of the last conversation the caller holds. The response used
  // to be `{ conversations }` alone, so a caller asking for `limit` rows could
  // not tell a full last page from a truncated one. The server half is
  // objectstack-ai/cloud#2426.
  const conv = (id: string) => ({
    id, messages: [], createdAt: '2026-09-27T10:00:00Z', updatedAt: '2026-09-27T10:00:00Z',
  });

  it('accepts a page carrying `hasMore`, both values, and keeps it through parse', () => {
    const more = ListAiConversationsResponseSchema.parse({ conversations: [conv('c2'), conv('c1')], hasMore: true });
    expect(more.hasMore).toBe(true);
    expect(more.conversations.map((c) => c.id)).toEqual(['c2', 'c1']);
    expect(ListAiConversationsResponseSchema.parse({ conversations: [], hasMore: false }).hasMore).toBe(false);
  });

  it('REFUSES a page without `hasMore` — the flag is required, never an absent-means-unknown optional', () => {
    const r = ListAiConversationsResponseSchema.safeParse({ conversations: [conv('c1')] });
    expect(r.success).toBe(false);
    expect(r.error!.issues).toHaveLength(1);
    expect(r.error!.issues[0]!.code).toBe('invalid_type');
    expect(r.error!.issues[0]!.path).toEqual(['hasMore']);
    expect(r.error!.issues[0]!.message).toBe('Invalid input: expected boolean, received undefined');
  });

  it('refuses a non-boolean `hasMore` — a stringly "false" is not a page signal', () => {
    const r = ListAiConversationsResponseSchema.safeParse({ conversations: [], hasMore: 'false' });
    expect(r.success).toBe(false);
    expect(r.error!.issues[0]!.code).toBe('invalid_type');
    expect(r.error!.issues[0]!.path).toEqual(['hasMore']);
  });

  it('declares no `nextCursor` — the next cursor is the last conversation\'s id, already on the page', () => {
    expect(Object.keys((ListAiConversationsResponseSchema as any).shape)).toEqual(['conversations', 'hasMore']);
  });

  it('the request keeps its three keys — `cursor` is described, not reshaped', () => {
    expect(Object.keys((ListAiConversationsRequestSchema as any).shape)).toEqual(['agentId', 'limit', 'cursor']);
    expect(ListAiConversationsRequestSchema.parse({ limit: 20, cursor: 'c1' })).toEqual({ limit: 20, cursor: 'c1' });
  });
});