objectstack-ai
diff --git a/‎.changeset/9736-twins-spec-by-reference.md‎
Lines changed: 40 additions & 0 deletions b/‎.changeset/9736-twins-spec-by-reference.md‎
Lines changed: 40 additions & 0 deletions
diff --git a/‎packages/types/src/__tests__/dashboard-aria-retired-contract-twins.test.ts‎
Lines changed: 27 additions & 19 deletions b/‎packages/types/src/__tests__/dashboard-aria-retired-contract-twins.test.ts‎
Lines changed: 27 additions & 19 deletions
diff --git a/‎packages/types/src/__tests__/twins-spec-by-reference-9736.test.ts‎
Lines changed: 146 additions & 0 deletions b/‎packages/types/src/__tests__/twins-spec-by-reference-9736.test.ts‎
Lines changed: 146 additions & 0 deletions
@@ -0,0 +1,40 @@
+---
+'@object-ui/types': minor
+---
+
+feat(types): `AppComponentSchema`, `DashboardComponentSchema` and `PageNodeSchema` take the spec by reference, like their zod mirrors
+
+The three published zod mirrors have long taken `@objectstack/spec`'s `App` / `Dashboard` /
+`Page` surface by reference (`BaseSchema.extend(SpecXFields.shape)`), while their hand-written
+TypeScript twins restated only the members the renderers read. So the published validator
+admitted keys the published type did not declare: the package-lock envelope (`_lock`,
+`_lockReason`, `_lockSource`, `_provenance`, `_packageId`, `_packageVersion`, `_lockDocsUrl`,
+written by the packaging pipeline), `protection`, the app's `isDefault` / `_unpublished` /
+`defaultAgent` / `contextSelectors`, and the page's `source` / `interfaceConfig` / `requires`.
+The spec's retirement tombstones reached the type only as `any`, through `BaseSchema`'s index
+signature.
+
+Each twin now extends `Omit` over the spec's exported input type, and that `Omit` reads the same
+`as const` exclusion array the mirror's `specFieldsExcept` call reads. The two faces therefore
+project one spec surface, and a later spec bump moves both of them together:
+
+- **Admitted keys are declared** with the spec's own member types. A reader of a served document
+  can read `app.protection`, `page.requires` or the envelope without a cast.
+- **Tombstones refuse at compile time.** `version`, `homePageId`, `objects`, `apis`, `sharing`,
+  `embed`, `mobileNavigation` and `aria` on an app, and `aria`, `refreshInterval` and
+  `performance` on a dashboard, are now optional members typed `undefined`. Authoring a value is
+  a TypeScript error, which is the verdict the validator already gave at parse. ⚠️ This is the
+  one breaking edge: code that wrote one of these keys used to compile against the index
+  signature and was refused at parse. It is now refused by `tsc`, before it runs.
+- `DashboardComponentSchema.header` and `PageNodeSchema.slots` keep their own hand-written types.
+  Both are withheld from the spec projection on the type side only, because neither type is
+  assignable to the spec's member. The drift is already recorded in the parity ledgers.
+  `PageNodeSchema.assignedProfiles` is withheld the same way, but for forward compatibility:
+  objectstack `main` retires the key, and the hand-written `string[]` member (unchanged) would
+  otherwise stop compiling at the next spec bump. Its retirement is tracked separately.
+
+Why this is a minor bump: the published type surface gains members, and one authoring
+spelling moves from a parse-time refusal to a compile-time refusal. This repo marks breaking
+semantics `minor` rather than `major`.
+
+This change affects types only. It changes no runtime code and narrows no mirror.
@@ -21,17 +21,19 @@
  * `AriaPropsSchema`, the opposite of the contract: the member-level instance
  * of #4631's "declared surfaces disagree".
  *
- * What the deletion changes at the type level, stated honestly: `BaseSchema`
- * carries `[key: string]: any`, so an authored `aria:` on a dashboard literal
- * still COMPILES after the removal — it falls to the index signature. A
- * `@ts-expect-error` pin on an authored literal therefore cannot stick here
- * (unlike `default-children-retired-contract-twins.test.ts`, whose interface
- * has no index signature). The pinnable effect is that `aria` stops being a
- * DECLARED member: the probe below extracts the interface's literal key set —
- * the index signature is filtered out by `string extends K` — and asserts
- * `aria` is out while its former neighbours stay in. Real enforcement because
- * `packages/types/tsconfig.test.json` is chained from this package's
- * `type-check` script (#3009).
+ * What the deletion changed at the type level, stated honestly: `BaseSchema`
+ * carries `[key: string]: any`, so after the removal an authored `aria:` on a
+ * dashboard literal still COMPILED — it fell to the index signature, and a
+ * `@ts-expect-error` pin on an authored literal could not stick.
+ *
+ * objectui#9736 closed that half. The interface now extends the spec's own
+ * `Dashboard` input type (`Omit< Dashboard, … >` over the exclusion list its
+ * mirror reads), so it inherits the spec's tombstone as a DECLARED member typed
+ * `undefined` — `aria` is back in the declared key set, but only as a refusal,
+ * and an authored value is a compile error: the same verdict the Zod twin gives
+ * at parse. The pins below assert exactly that, with the former neighbours as
+ * the control. Real enforcement because `packages/types/tsconfig.test.json` is
+ * chained from this package's `type-check` script (#3009).
  */
 
 import { describe, it, expect } from 'vitest';
@@ -43,18 +45,24 @@ import { DashboardComponentSchema as DashboardComponentZodSchema } from '../zod/
 type DeclaredKeys<T> = { [K in keyof T as string extends K ? never : K]: T[K] };
 type Declared = keyof DeclaredKeys<DashboardComponentSchema>;
 
-describe('the TS interface no longer declares `aria` (objectui#5830)', () => {
-  it('`aria` is not a declared member; the neighbours it stood beside still are', () => {
-    // Type-level pin, erased at runtime: if the member came back, the first
-    // annotation would collapse to `false` and this file would fail
-    // `type-check`. (Reverse-verified at the PR: with the member restored,
-    // `tsc -p tsconfig.test.json` goes red on exactly this line.)
-    const ariaNotDeclared: 'aria' extends Declared ? false : true = true;
+describe('the TS interface declares `aria` only as the spec tombstone (objectui#5830, objectui#9736)', () => {
+  it('`aria` is declared, typed `undefined`; the neighbours it stood beside still are', () => {
+    // Type-level pins, erased at runtime. `aria` is a DECLARED key again — the
+    // spec projection carries the tombstone — and its type admits no value.
+    const ariaDeclared: 'aria' extends Declared ? true : false = true;
+    const ariaAdmitsNoValue: [DashboardComponentSchema['aria']] extends [undefined] ? true : false = true;
     // Positive controls through the same extraction: a probe that saw no
     // members at all would also report `aria` absent.
     const widgetsDeclared: 'widgets' extends Declared ? true : false = true;
     const dateRangeDeclared: 'dateRange' extends Declared ? true : false = true;
-    expect(ariaNotDeclared && widgetsDeclared && dateRangeDeclared).toBe(true);
+    expect(ariaDeclared && ariaAdmitsNoValue && widgetsDeclared && dateRangeDeclared).toBe(true);
+  });
+
+  it('an authored `aria` value is a compile error — no longer absorbed by the index signature', () => {
+    const legal: DashboardComponentSchema = { type: 'dashboard', widgets: [] };
+    // @ts-expect-error — `aria` is the spec's retirement tombstone (objectui#9736).
+    const authored: DashboardComponentSchema = { type: 'dashboard', widgets: [], aria: { ariaLabel: 'Ops' } };
+    expect([legal.type, authored.type]).toEqual(['dashboard', 'dashboard']);
   });
 });
 
 
@@ -0,0 +1,146 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * objectui#9736 — the three hand-written TypeScript twins take the spec BY
+ * REFERENCE, the way their zod mirrors do (ruling batch #167 item 4, letter 甲).
+ *
+ * `AppComponentSchema` / `DashboardComponentSchema` / `PageNodeSchema` each
+ * extend `Omit< App | Dashboard | Page, … >` over the SAME `as const` exclusion
+ * array their mirror's `specFieldsExcept` call reads (`APP_SPEC_EXCLUDED`,
+ * `DASHBOARD_SPEC_EXCLUDED`, `PAGE_SPEC_EXCLUDED`), plus — on the TypeScript
+ * face only — the twin members whose hand-written type is not assignable to
+ * the spec's (`header` on the dashboard, `slots` on the page, both already
+ * ledgered as drift in `zod-mirror-parity.test.ts`), plus the page's
+ * `assignedProfiles`, which objectstack `main` retires (a forward-compat
+ * omission, objectui#9409).
+ *
+ * ## Why the positive pins are TYPE equalities, not assignments
+ *
+ * `BaseSchema` carries `[key: string]: any`, so an object literal carrying ANY
+ * key compiles against these interfaces whether or not the key is declared —
+ * an "it compiles" pin would be green on the tree before this change. So:
+ *   - declared-ness is read through `DeclaredKeys`, which filters the index
+ *     signature out (`string extends K`);
+ *   - member types are compared with `Equal`, against the spec's own member;
+ *   - the tombstone half is a `@ts-expect-error` on an authored value, which
+ *     only sticks BECAUSE the key is now declared (the index signature would
+ *     have absorbed it as `any` — `dashboard-aria-retired-contract-twins` is the
+ *     record of that pin not sticking before).
+ *
+ * Real enforcement because `packages/types/tsconfig.test.json` is chained from
+ * this package's `type-check` script; the runtime half asserts the mirror
+ * gives the same verdict on the same literal.
+ */
+
+import { describe, it, expect } from 'vitest';
+import type { App, Dashboard, Page } from '@objectstack/spec/ui';
+import type { AppComponentSchema } from '../app';
+import type { DashboardComponentSchema } from '../complex';
+import type { PageNodeSchema } from '../layout';
+import {
+  AppComponentSchema as AppMirror,
+  DashboardComponentSchema as DashboardMirror,
+  PageNodeSchema as PageMirror,
+} from '../zod/index.zod';
+
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+type DeclaredKeys<T> = keyof { [K in keyof T as string extends K ? never : K]: T[K] };
+
+/** Keys the spec's document type declares that the twin does NOT declare. */
+type SpecKeysUndeclaredOn<Spec, Twin> = Exclude<keyof Spec, DeclaredKeys<Twin>>;
+
+describe('each twin declares every key its spec document type declares', () => {
+  it('App / Dashboard / Page: the spec-minus-declared key set is empty', () => {
+    // Before objectui#9736 these read as the MirroredUndeclared rows (20 / 11 / 10
+    // keys). ⭐ Control: `DeclaredKeys` must see real members, or `never` above is
+    // vacuous — `protection` / `requires` are keys ONLY the spec projection brings.
+    const app: Equal<SpecKeysUndeclaredOn<App, AppComponentSchema>, never> = true;
+    const dashboard: Equal<SpecKeysUndeclaredOn<Dashboard, DashboardComponentSchema>, never> = true;
+    const page: Equal<SpecKeysUndeclaredOn<Page, PageNodeSchema>, never> = true;
+    const controlApp: 'protection' extends DeclaredKeys<AppComponentSchema> ? true : false = true;
+    const controlPage: 'requires' extends DeclaredKeys<PageNodeSchema> ? true : false = true;
+    const controlNegative: 'notASpecKey9736' extends DeclaredKeys<AppComponentSchema> ? true : false = false;
+    expect([app, dashboard, page, controlApp, controlPage, controlNegative]).toEqual([true, true, true, true, true, false]);
+  });
+});
+
+describe('admitted spec keys land on the twin with the SPEC\'S type, not `any`', () => {
+  it('the package-lock envelope and document keys equal the spec member', () => {
+    const lock: Equal<AppComponentSchema['_lock'], App['_lock']> = true;
+    const appProtection: Equal<AppComponentSchema['protection'], App['protection']> = true;
+    const defaultAgent: Equal<AppComponentSchema['defaultAgent'], App['defaultAgent']> = true;
+    const dashProtection: Equal<DashboardComponentSchema['protection'], Dashboard['protection']> = true;
+    const dashPackageId: Equal<DashboardComponentSchema['_packageId'], Dashboard['_packageId']> = true;
+    const pageSource: Equal<PageNodeSchema['source'], Page['source']> = true;
+    const pageRequires: Equal<PageNodeSchema['requires'], Page['requires']> = true;
+    const pageInterfaceConfig: Equal<PageNodeSchema['interfaceConfig'], Page['interfaceConfig']> = true;
+    // Control: an undeclared key reads as `any` through the index signature, and
+    // `Equal` tells `any` apart from a real member type.
+    const anyControl: Equal<AppComponentSchema['notASpecKey9736'], App['_lock']> = false;
+    expect([lock, appProtection, defaultAgent, dashProtection, dashPackageId, pageSource, pageRequires, pageInterfaceConfig, anyControl])
+      .toEqual([true, true, true, true, true, true, true, true, false]);
+  });
+
+  it('`contextSelectors` — withheld from the projection — is declared over the mirror\'s own element', () => {
+    const declared: 'contextSelectors' extends DeclaredKeys<AppComponentSchema> ? true : false = true;
+    const selectors: AppComponentSchema['contextSelectors'] = [
+      { id: 'pkg', label: 'Package', optionsSource: { endpoint: '/api/v1/packages' } },
+    ];
+    expect(declared).toBe(true);
+    expect(AppMirror.safeParse({ type: 'app', contextSelectors: selectors }).success).toBe(true);
+  });
+});
+
+describe('spec tombstones surface on the twin as a refusal — the verdict the mirror gives', () => {
+  it('App `version` / Dashboard `refreshInterval`: authoring a value is a compile error AND a parse failure', () => {
+    // @ts-expect-error — `version` is the spec's `retiredKey()` tombstone.
+    const app: AppComponentSchema = { type: 'app', version: '1.0.0' };
+    // @ts-expect-error — `refreshInterval` is the #15680 rename's tombstone.
+    const dashboard: DashboardComponentSchema = { type: 'dashboard', widgets: [], refreshInterval: 30 };
+    expect(AppMirror.safeParse(app).success).toBe(false);
+    expect(DashboardMirror.safeParse(dashboard).success).toBe(false);
+  });
+
+  it('the controls: the same documents without the tombstone key pass both faces', () => {
+    const app: AppComponentSchema = { type: 'app' };
+    const dashboard: DashboardComponentSchema = { type: 'dashboard', widgets: [], refreshIntervalSeconds: 30 };
+    expect(AppMirror.safeParse(app).success).toBe(true);
+    expect(DashboardMirror.safeParse(dashboard).success).toBe(true);
+  });
+
+  it('`Page` carries no tombstone on the installed pin — its admitted keys pass both faces', () => {
+    // ⚠️ Recorded rather than assumed: the spec's `PageSchema` has no
+    // `retiredKey()` member on @objectstack/spec 17.4.0, so the page twin's pin
+    // is the admitted half only.
+    const page: PageNodeSchema = { type: 'page', source: 'pages/home.tsx', requires: ['crm'] };
+    expect(PageMirror.safeParse(page).success).toBe(true);
+  });
+});
+
+describe('the twin-only omissions keep the twin\'s own member, unwidened', () => {
+  it('Dashboard `header` and Page `slots` are the hand-written types, not the spec\'s', () => {
+    type HeaderAction = NonNullable<NonNullable<DashboardComponentSchema['header']>['actions']>[number];
+    const headerLabel: Equal<HeaderAction['label'], string> = true;
+    const headerNotSpec: Equal<DashboardComponentSchema['header'], Dashboard['header']> = false;
+    const slotsNotSpec: Equal<PageNodeSchema['slots'], Page['slots']> = false;
+    expect([headerLabel, headerNotSpec, slotsNotSpec]).toEqual([true, false, false]);
+  });
+
+  it('Page `assignedProfiles` keeps the hand-written `string[]` whatever the spec pin declares', () => {
+    // A FORWARD-COMPAT omission: objectstack `main` retires the key (its input
+    // type becomes `undefined`), and the hand-written member would then stop
+    // compiling in the `extends` clause. Spelling it beside the shared list keeps
+    // the twin compiling against both the installed pin and `main` (the
+    // `Spec Main Shape Gate`). Retiring it is objectui#9409's decision, ⛔ not
+    // this file's, so the member must stay exactly what it was.
+    const assignedProfiles: Equal<PageNodeSchema['assignedProfiles'], string[] | undefined> = true;
+    const declared: 'assignedProfiles' extends DeclaredKeys<PageNodeSchema> ? true : false = true;
+    expect([assignedProfiles, declared]).toEqual([true, true]);
+  });
+});