objectstack-ai
diff --git a/‎.changeset/17885-artifact-door-default-flip-class.md‎
Lines changed: 15 additions & 0 deletions b/‎.changeset/17885-artifact-door-default-flip-class.md‎
Lines changed: 15 additions & 0 deletions
diff --git a/‎packages/metadata-core/src/artifact-forward-conversion.test.ts‎
Lines changed: 139 additions & 1 deletion b/‎packages/metadata-core/src/artifact-forward-conversion.test.ts‎
Lines changed: 139 additions & 1 deletion
diff --git a/‎packages/metadata-core/src/artifact-forward-conversion.ts‎
Lines changed: 49 additions & 1 deletion b/‎packages/metadata-core/src/artifact-forward-conversion.ts‎
Lines changed: 49 additions & 1 deletion
diff --git a/‎packages/spec/src/conversions/apply.ts‎
Lines changed: 36 additions & 1 deletion b/‎packages/spec/src/conversions/apply.ts‎
Lines changed: 36 additions & 1 deletion
@@ -0,0 +1,15 @@
+---
+"@objectstack/spec": minor
+"@objectstack/metadata-core": patch
+---
+
+The artifact-ingestion door no longer replays the **default-flip** class of ADR-0087 conversion, so an artifact carrying `defineApp({ hidden: true })` is registered with `hidden: true` — not as an unpublished app (#17885, #4829).
+
+`app-hidden-to-unpublished` rewrites `app.hidden: true` into `app._unpublished: true`. Both keys are live and they mean opposite kinds of thing: `hidden` is navigation presentation and *"never an access gate"* (`ui/app.zod.ts`), while `_unpublished` is the machine-managed publish gate `filterAppForUser` drops the app on for every user without `studio.access` / `setup.access`. Measured before the change, on an artifact declaring `engines.protocol: ^17.0.0` — the range `create-objectstack` stamps — against a 17.4.0 runtime: the door emitted the `app-hidden-to-unpublished` notice and the object that reached registration carried `hidden: undefined`, `_unpublished: true`. So an author who asked for "keep this out of the App Switcher" got "nobody but a builder can see this" — the incident the `_unpublished` split was introduced to end, arriving through the conversion layer.
+
+- **The entry is not withdrawn and no key moves.** It still fires where its precondition is a fact — the stored-row rehydration seams (a pre-split `hidden: true` row can only have come from the materialization path) and `os migrate meta`, where the operator asserts the source's age. What changed is that the artifact door, whose evidence is the artifact's **declared `engines.protocol` floor** rather than its age, no longer treats that guess as sufficient for a rewrite that reinterprets a live authorable key.
+- **The retired window stays open.** Closing it wholesale would fix this and re-break #12772: an artifact built by 17.1.0 tooling carrying `allowRestore` / `allowPurge` would again be refused at the tombstone with no operator remedy. The door refuses one named class by id, with its reason written beside it, and the pin drives a retired conversion and a non-retired one through the same window to prove it.
+- **New seam option, no new export.** `applyConversions` accepts `excludeConversionIds` — the seat-level spelling of "my evidence cannot carry this entry". `retiredFromLoadPath` cannot express it: that flag's jurisdiction is the authoring funnel and nothing else.
+- ⛔ **The consumer is unchanged.** `filterAppForUser` withholding on `_unpublished` is correct; the defect was who writes `_unpublished`.
+
+Deployments whose apps were being served as unpublished purely because of a permissive `engines.protocol` range will see those apps again, for every user, on the next boot. No artifact file changes and no stored row is rewritten.
@@ -17,7 +17,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import type { ConversionNotice } from '@objectstack/spec';
+import { ObjectStackDefinitionSchema, applyConversionsToStoredItem, type ConversionNotice } from '@objectstack/spec';
 import {
   applyArtifactForwardConversions,
   parseRangeFloor,
@@ -263,6 +263,144 @@ describe('the artifact door never stamps a column constraint (ADR-0113, #16693)'
   });
 });
 
+/**
+ * #17885 — the artifact door must not replay the DEFAULT-FLIP class.
+ *
+ * `app-hidden-to-unpublished` (#4829, ADR-0045 amended 2026-08-09) rewrites
+ * `app.hidden: true` into `app._unpublished: true`. Both keys are live and
+ * they mean opposite kinds of thing: `hidden` is navigation presentation and
+ * *"never an access gate"* (`ui/app.zod.ts`), while `_unpublished` is the
+ * machine-managed publish gate `filterAppForUser` drops the app on for every
+ * user without `studio.access` / `setup.access`
+ * (`packages/rest/src/rest-server.ts` — untouched by this fix, and correct:
+ * the defect is WHO writes `_unpublished`).
+ *
+ * The entry is `retiredFromLoadPath: true`, which does NOT hold it back here —
+ * that flag's jurisdiction is the authoring funnel and nothing else (#16864's
+ * determination, landed). So before this fix an artifact declaring
+ * `engines.protocol: ^17.0.0` — the range `create-objectstack` stamps — had
+ * every `defineApp({ hidden: true })` in it registered as an unpublished app,
+ * reproducing the very incident the `_unpublished` split was introduced to
+ * end, through the conversion layer.
+ *
+ * Four legs, and the two controls are what make the first two mean anything:
+ * SUBJECT (the window is open and `hidden` survives) · NEGATIVE (a floor the
+ * window is shut for) · POSITIVE, twice (a non-retired conversion AND a
+ * retired one still fire in the subject's own window — the door is narrowed,
+ * not closed) · and the entry itself still firing at the seam it is sound at.
+ */
+describe('the artifact door never turns an authored `hidden: true` into an unpublished app (#17885, #4829)', () => {
+  /** One authored `hidden: true` app, plus a `jsx` page as the live non-retired control. */
+  const hiddenAppDefinition = (protocolRange: string) => ({
+    manifest: {
+      id: 'app.example.hr', name: 'hr', version: '1.0.0', type: 'app',
+      engines: { protocol: protocolRange },
+    },
+    apps: [{ name: 'account', label: 'Account', hidden: true, navigation: [] }],
+  });
+
+  it('leaves `hidden: true` alone on an artifact the retired window IS open for', () => {
+    const def = hiddenAppDefinition('^17.0.0');
+    const result = applyArtifactForwardConversions(def, { runtimeSpecVersion: '17.4.0' });
+
+    // ⭐ ANTI-VACUITY: the window really is open on this input. A green line
+    // below because the door skipped the artifact would prove nothing.
+    expect(result.verdict).toBe('converted-forward');
+    expect(result.authoredFloor).toBe('17.0.0');
+
+    const app = (result.definition as { apps: Record<string, unknown>[] }).apps[0]!;
+    expect(app.hidden, 'the authored navigation choice is untouched').toBe(true);
+    expect(app._unpublished, 'no publish gate is invented for the author').toBeUndefined();
+    expect(result.notices.map((n) => n.conversionId)).not.toContain('app-hidden-to-unpublished');
+    // Copy-on-write: nothing was recognized, so the same reference comes back.
+    expect(result.definition).toBe(def);
+  });
+
+  /**
+   * ⭐⭐ The assertion that actually matters: the door's output is fed to
+   * `ObjectStackDefinitionSchema.parse` in `MetadataPlugin._parseAndRegisterArtifact`,
+   * and THAT object is what reaches registration and then `filterAppForUser`.
+   * A pin on the conversion's return value alone would not have caught a strict
+   * parse that re-introduced the key.
+   */
+  it('registers `hidden: true` — asserted AFTER the strict parse the door feeds', () => {
+    const def = hiddenAppDefinition('^17.0.0');
+    const result = applyArtifactForwardConversions(def, { runtimeSpecVersion: '17.4.0' });
+    expect(result.verdict).toBe('converted-forward');
+
+    const parsed = ObjectStackDefinitionSchema.parse(result.definition) as {
+      apps?: { name: string; hidden?: boolean; _unpublished?: boolean }[];
+    };
+    const registered = parsed.apps!.find((a) => a.name === 'account')!;
+    expect(registered.hidden, 'what registration receives').toBe(true);
+    expect(registered._unpublished, 'what `filterAppForUser` withholds on').toBeUndefined();
+  });
+
+  /**
+   * ⭐ NEGATIVE CONTROL — the instrument can answer "no" for the other reason.
+   * A floor at or above the runtime shuts the window outright, so `hidden`
+   * surviving here says nothing about the fix; it says the leg above was read
+   * on an input where the window was genuinely open.
+   */
+  it('floor ^99.0.0 — the window is shut and nothing is replayed at all', () => {
+    const def = hiddenAppDefinition('^99.0.0');
+    const result = applyArtifactForwardConversions(def, { runtimeSpecVersion: '17.4.0' });
+    expect(result.verdict).toBe('authored-current');
+    expect(result.notices).toEqual([]);
+    expect((result.definition as { apps: Record<string, unknown>[] }).apps[0]!.hidden).toBe(true);
+  });
+
+  /**
+   * ⭐ FIRING CONTROL 1 — a NON-RETIRED conversion still fires in the subject's
+   * own window. `page-kind-jsx-to-html` (ADR-0080) is not retired, so a door
+   * that had stopped converting anything would fail here.
+   */
+  it('still applies a non-retired conversion in that same window', () => {
+    const def = {
+      ...hiddenAppDefinition('^17.0.0'),
+      pages: [{ name: 'landing', kind: 'jsx', source: '<div>hi</div>' }],
+    };
+    const result = applyArtifactForwardConversions(def, { runtimeSpecVersion: '17.4.0' });
+    expect(result.verdict).toBe('converted-forward');
+    expect(result.notices.map((n) => n.conversionId)).toContain('page-kind-jsx-to-html');
+    expect((result.definition as { pages: Record<string, unknown>[] }).pages[0]!.kind).toBe('html');
+    // …and the app in the SAME artifact still keeps its authored key.
+    expect((result.definition as { apps: Record<string, unknown>[] }).apps[0]!.hidden).toBe(true);
+  });
+
+  /**
+   * ⭐ FIRING CONTROL 2 — and the RETIRED window is still open, which is the
+   * control this particular fix could plausibly have broken. Closing the
+   * retired window wholesale would fix #17885 and re-break #12772: an artifact
+   * built by 17.1.0 tooling would again be refused at the tombstone.
+   */
+  it('still replays RETIRED conversions in that same window (#12772 is not reversed)', () => {
+    const def = legacyPermissionDefinition('^17.0.0');
+    const result = applyArtifactForwardConversions(def, { runtimeSpecVersion: '17.4.0' });
+    expect(result.verdict).toBe('converted-forward');
+    const objects = (result.definition as { permissions: { objects: Record<string, Record<string, unknown>> }[] })
+      .permissions[0]!.objects;
+    expect(objects.crm_ticket!.allowRestore).toBeUndefined();
+    expect(objects.crm_ticket!.allowPurge).toBeUndefined();
+    expect(result.notices.length).toBeGreaterThan(0);
+  });
+
+  /**
+   * ⭐ SEAM SCOPE — the entry is refused by THIS DOOR, not removed from the
+   * chain. The stored-row seam, where a `hidden: true` row can only have come
+   * from the pre-split materialization path, still carries the population
+   * across. A fix that had neutered the entry would go green on every leg
+   * above and silently strand those rows.
+   */
+  it('leaves the entry firing at the stored-row seam it is sound at', () => {
+    const row = applyConversionsToStoredItem('app', {
+      name: 'production_management', label: 'Production', hidden: true, navigation: [],
+    }) as Record<string, unknown>;
+    expect(row._unpublished, 'the stored-row seam still converts').toBe(true);
+    expect(row.hidden).toBeUndefined();
+  });
+});
+
 describe('parseRangeFloor — the range spellings artifacts actually carry', () => {
   it.each([
     ['^17.1.0', [17, 1, 0]],
 
@@ -62,11 +62,35 @@
  * Cross-major gaps are the protocol *handshake*'s jurisdiction
  * (`checkProtocolCompat`) and refuse before conversion could matter.
  *
+ * ## The one class the window does NOT admit — default flips
+ *
+ * The window above is a RESCUE: without it an artifact carrying a key the
+ * current schema has since tombstoned is refused outright, with no operator
+ * remedy. Every entry of that kind is safe to replay here, because the old
+ * shape has no live meaning left to destroy.
+ *
+ * A DEFAULT FLIP is not that. Its old shape still parses, still means
+ * something on today's authoring surface, and the rewrite changes what it
+ * means — so replaying it is a reinterpretation, sound only where "this input
+ * predates the flip" is a FACT. At this door it is a GUESS, and a weak one:
+ * the key is the artifact's **declared `engines.protocol` floor**, not its
+ * age, and `^17.0.0` is the range `create-objectstack` stamps — so an app
+ * authored today, against today's surface, lands inside the window (measured
+ * for `field-required-notnull-explicit`, #16693; measured again for
+ * `app-hidden-to-unpublished`, #17885). Retirement does not hold those back
+ * either: `retiredFromLoadPath`'s jurisdiction is the AUTHORING funnel and
+ * nothing else (#16864's determination, and the flag's own docblock now says
+ * so) — which is exactly why the window has to name them here.
+ *
+ * ⇒ {@link DEFAULT_FLIPS_NOT_REPLAYED_HERE} lists them, and the door refuses
+ * them by id. Each id owes its reason beside it.
+ *
  * ## What this deliberately is NOT
  *
  * - Not a second conversion table: the ADR-0087 registry in
  *   `@objectstack/spec` stays the single authority on *what* converts; this
- *   module only decides *whether the retired window opens* for one artifact.
+ *   module only decides *whether the retired window opens* for one artifact —
+ *   now per entry for the one named class above, rather than all-or-nothing.
  * - Not a validator: like `applyConversions` itself, this never throws and
  *   never gates. Gating stays at the caller's schema parse.
  * - Not the flow-specific seam: flows convert here too (context-less, exactly
@@ -243,6 +267,29 @@ export function resolveInstalledSpecVersion(): string | null {
   return null;
 }
 
+/**
+ * ADR-0087 entries the versioned window deliberately does NOT replay here —
+ * the DEFAULT-FLIP class (see the module doc). Module-local on purpose: this
+ * is the door's own refusal, not a fact about the registry, and exporting it
+ * would invite a second caller to inherit a judgement it has not made.
+ *
+ * - `app-hidden-to-unpublished` (#17885, #4829, ADR-0045 amended 2026-08-09):
+ *   rewrites `app.hidden: true` into `app._unpublished: true`. `hidden` is a
+ *   LIVE authorable key — navigation presentation, *"never an access gate"*
+ *   (`ui/app.zod.ts`) — while `_unpublished` is the machine-managed publish
+ *   gate that `filterAppForUser` (`packages/rest/src/rest-server.ts`) drops
+ *   the app on for every user without `studio.access` / `setup.access`. So
+ *   replaying it here turns an authored `defineApp({ hidden: true })` into an
+ *   app nobody but a builder can see — reproducing #4829, the incident the
+ *   `_unpublished` split was introduced to end, through the conversion layer.
+ *   The entry is sound where it says it is (the stored-row rehydration seams,
+ *   where a `hidden: true` row can only have come from the pre-split
+ *   materialization path, and `os migrate meta --from <=16`, where the
+ *   operator asserts the source's age) — this door is neither, so it opts out
+ *   rather than the entry ceasing to fire.
+ */
+const DEFAULT_FLIPS_NOT_REPLAYED_HERE: readonly string[] = ['app-hidden-to-unpublished'];
+
 /**
  * Apply the versioned forward conversion to one compiled-artifact definition.
  *
@@ -289,6 +336,7 @@ export function applyArtifactForwardConversions<T>(
   const notices: ArtifactConversionNotice[] = [];
   const converted = applyConversions(definition as Record<string, unknown>, {
     includeRetired: true,
+    excludeConversionIds: DEFAULT_FLIPS_NOT_REPLAYED_HERE,
     onNotice: (n) => {
       notices.push(n);
       options.onNotice?.(n);
 
@@ -70,6 +70,34 @@ export interface ApplyConversionsOptions {
    * rather than silently clobber it.
    */
   reservedNodeTypes?: ReadonlySet<string>;
+  /**
+   * Conversion ids this seam refuses to replay, whatever `includeRetired`
+   * says. Empty/absent by default: every seam replays the whole window it
+   * opened.
+   *
+   * **Why a seam needs this at all.** `includeRetired` opens the window for a
+   * WHOLE CLASS of caller (data at rest), and the entries inside that window
+   * are not one kind. Most are lossless deletes or renames of a shape the
+   * current schema now REFUSES — replaying those is the rescue the window
+   * exists for, because without it the row or artifact is simply unbootable.
+   * A few are DEFAULT FLIPS: the old shape still parses, still means
+   * something, and the rewrite changes what it means. For those the replay is
+   * not a rescue, it is a reinterpretation — and whether it is sound depends
+   * on the CALLER, not on the entry: only a seam that can say "this input
+   * predates the flip" as a FACT rather than a guess may apply one.
+   *
+   * ⇒ The entry cannot answer that (nothing in the item distinguishes a
+   * machine-written row at rest from an author who wrote the same key
+   * yesterday), and `retiredFromLoadPath` does not answer it either — its
+   * jurisdiction is the authoring funnel and nothing else (see that flag's
+   * own docblock on `MetadataConversion`). This option is where a seam says
+   * which entries its own evidence cannot carry.
+   *
+   * ⛔ NOT a second conversion table and never a filter of convenience: the
+   * registry stays the single authority on WHAT converts. A caller passing
+   * this owes a written reason per id, at the call site.
+   */
+  excludeConversionIds?: readonly string[];
 }
 
 /**
@@ -84,10 +112,17 @@ export function applyConversions(
   stack: Record<string, unknown>,
   options: ApplyConversionsOptions = {},
 ): Record<string, unknown> {
-  const { onNotice, onConflict, reservedNodeTypes, includeRetired = false } = options;
+  const { onNotice, onConflict, reservedNodeTypes, includeRetired = false, excludeConversionIds } = options;
+  const excluded = excludeConversionIds && excludeConversionIds.length > 0
+    ? new Set(excludeConversionIds)
+    : null;
   let current = stack;
 
   for (const conversion of ALL_CONVERSIONS) {
+    // The seam's own refusal, read BEFORE the retirement window: a caller that
+    // cannot carry a given entry's precondition does not get it back by
+    // opening the window (see `excludeConversionIds`).
+    if (excluded?.has(conversion.id)) continue;
     // A retired entry is graduated chain history (ADR-0087 D2 window, second
     // half): the AUTHORING funnel (`normalizeStackInput`) no longer replays it,
     // so the tombstone teaches the author instead. The data-at-rest seams —