fix(spec): the top-level lint must not call a working onEnable dropped

Caught by running the new lint against our own shipped examples before
merging: `examples/app-todo` and `examples/app-showcase` both got

  ⚠ stack.onEnable: 'onEnable' is not a declared stack key, so its value is
    dropped at load.

which is false. `onEnable` is a function, so `ObjectStackDefinitionSchema`
cannot declare it and `dist/objectstack.json` cannot carry it — but `AppPlugin`
reads it straight off the authored bundle and calls it at `start()`
(`app-plugin.ts`), and the artifact-boot path grafts it back (#4095). It is the
documented place to register action handlers. "Not declared" and "dropped at
load" are different claims, and this is the one surface where they come apart.

New `STACK_RUNTIME_MEMBERS` names the authored top-level members the runtime
honours off the bundle; `lintUnknownStackKeys` treats them as declared. The
CLI's `GRAFTABLE_RUNTIME_MEMBERS` is now DERIVED from it instead of restating
it — two hand-written copies could disagree, and the disagreement would be
silent in exactly the direction this lint family exists to catch.

`onDisable` is deliberately excluded from the exemption: it is declared in the
protocol but no kernel, runtime or service calls it, so a value written there
really does go nowhere. A test pins both halves of that distinction.

Re-harvested after the fix: all three shipped examples validate with zero
undeclared-key warnings.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh

Author: claude

.changeset/stack-storage-not-an-authoring-key.md

@@ -35,6 +35,19 @@ path and disappeared silently everywhere else. A host writing
   #4096. That command reconciles what records claim against what storage holds,
   so a disagreeing root reconciled against the wrong tree.
 
+**`onEnable` is exempt, and the exemption has one owner.** `onEnable` is a
+function, so `ObjectStackDefinitionSchema` cannot declare it and
+`dist/objectstack.json` cannot carry it — but it is not lost: `AppPlugin` calls
+it off the authored bundle, and the artifact-boot path grafts it back (#4095).
+"Not declared" and "dropped at load" are different claims, and this is the
+surface where they come apart. New `STACK_RUNTIME_MEMBERS` in `@objectstack/spec`
+names the members the runtime honours off the bundle; the lint treats them as
+declared, and the CLI's `GRAFTABLE_RUNTIME_MEMBERS` is now **derived** from it
+rather than restating it, so the list that decides what gets grafted and the
+list that decides what the lint stays quiet about cannot drift. `onDisable` is
+deliberately not on it — nothing calls it, so a value written there really does
+go nowhere and the lint should say so.
+
 Additive: `lintUnknownAuthoringKeys` keeps its signature. The new pass is a
 separate export rather than a fold into that walker for two reasons. The walker
 iterates metadata COLLECTIONS, so a stack whose only mistake is at the envelope

packages/cli/src/utils/graft-runtime-hooks.ts

@@ -28,6 +28,8 @@
 // invisible for so long.
 // ---------------------------------------------------------------------------
 
+import { STACK_RUNTIME_MEMBERS } from '@objectstack/spec';
+
 /**
  * Bundle members `AppPlugin` executes, and which therefore cannot survive a
  * trip through JSON:
@@ -40,8 +42,16 @@
  * `onDisable` is deliberately absent: it is declared in `packages/spec` but no
  * kernel, runtime or service ever calls it, so grafting it would wire a hook
  * nothing runs.
+ *
+ * **Derived, not restated** (framework#4167). The same list decides what the
+ * undeclared-top-level-key lint stays quiet about: these members are not
+ * declared by `ObjectStackDefinitionSchema`, but they are honoured off the
+ * authored bundle, so reporting them as "dropped at load" would be false. Two
+ * hand-written copies could disagree, and the disagreement would be silent in
+ * exactly the direction that lint exists to catch — so the protocol owns the
+ * list and this re-exports it.
  */
-export const GRAFTABLE_RUNTIME_MEMBERS = ['onEnable', 'functions'] as const;
+export const GRAFTABLE_RUNTIME_MEMBERS = STACK_RUNTIME_MEMBERS;
 
 export type GraftableRuntimeMember = (typeof GRAFTABLE_RUNTIME_MEMBERS)[number];
 

packages/spec/api-surface.json

@@ -92,6 +92,7 @@
     "PredicateInputSchema (const)",
     "PredicateSchema (const)",
     "STACK_KEY_GUIDANCE (const)",
+    "STACK_RUNTIME_MEMBERS (const)",
     "SemanticMigration (interface)",
     "Skill (type)",
     "SpecChanges (type)",
@@ -504,6 +505,7 @@
     "SSLConfig (type)",
     "SSLConfigSchema (const)",
     "STACK_KEY_GUIDANCE (const)",
+    "STACK_RUNTIME_MEMBERS (const)",
     "STRING_VALUE_TYPES (const)",
     "STRUCTURED_JSON_TYPES (const)",
     "Scalar (type)",

packages/spec/src/data/authoring-key-lint.ts

@@ -159,6 +159,35 @@ export const STACK_KEY_GUIDANCE: Readonly<
   },
 });
 
+/**
+ * Authored TOP-LEVEL members the **runtime executes off the bundle**, which the
+ * stack schema therefore does not — and cannot — declare.
+ *
+ * `onEnable` is a function. It cannot survive `ObjectStackDefinitionSchema`
+ * (which does not declare it) and it cannot survive `dist/objectstack.json`
+ * (JSON has no functions), yet it is not lost: `AppPlugin` reads it straight
+ * off the authored bundle and calls it at `start()`, and on the artifact-boot
+ * path the CLI grafts it back (#4095). It is the documented place to register
+ * action handlers, and `examples/app-todo` and `examples/app-showcase` both
+ * ship it.
+ *
+ * So the lint must stay SILENT here. "Not declared" and "dropped at load" are
+ * different claims, and this is the one surface where they come apart — telling
+ * an author their working `onEnable` is being discarded would be a confident
+ * lie about the pattern we ship in our own examples.
+ *
+ * `functions` is listed for the same reason (a name → handler map the runtime
+ * resolves string-named hooks against); the schema happens to declare it too,
+ * so it self-excludes. `onDisable` is deliberately ABSENT: it is declared in
+ * the protocol but no kernel, runtime or service ever calls it, so a value
+ * written there really does go nowhere and the lint should say so.
+ *
+ * Single source of truth — the CLI's `GRAFTABLE_RUNTIME_MEMBERS` is derived
+ * from this, so the list that decides what gets grafted and the list that
+ * decides what the lint stays quiet about cannot drift apart.
+ */
+export const STACK_RUNTIME_MEMBERS = Object.freeze(['onEnable', 'functions'] as const);
+
 /** A plain object — the only shape an authored metadata item can take. */
 export function isPlainRecord(v: unknown): v is Record<string, unknown> {
   return !!v && typeof v === 'object' && !Array.isArray(v);

packages/spec/src/index.ts

@@ -107,6 +107,7 @@ export {
   FIELD_KEY_GUIDANCE,
   OBJECT_KEY_GUIDANCE,
   STACK_KEY_GUIDANCE,
+  STACK_RUNTIME_MEMBERS,
 } from './data/authoring-key-lint';
 export type {
   UnknownAuthoringKeyFinding,

packages/spec/src/kernel/metadata-authoring-lint.test.ts

@@ -18,7 +18,7 @@ import {
   lintUnknownStackKeys,
   listLintableAuthoringCollections,
 } from './metadata-authoring-lint';
-import { STACK_KEY_GUIDANCE } from '../data/authoring-key-lint';
+import { STACK_KEY_GUIDANCE, STACK_RUNTIME_MEMBERS } from '../data/authoring-key-lint';
 import { PLURAL_TO_SINGULAR } from '../shared/metadata-collection.zod';
 import { ObjectStackDefinitionSchema } from '../stack.zod';
 import { getMetadataTypeSchema } from './metadata-type-schemas';
@@ -174,6 +174,24 @@ describe('top-level stack keys (#4167)', () => {
     expect(lint({ objects: [], pages: [], manifest: { name: 'app' }, _packageId: 'p' })).toEqual([]);
   });
 
+  it('stays silent on the runtime members the schema cannot declare', () => {
+    // The regression that shipped in review: `onEnable` is a function, so the
+    // schema does not declare it — but `AppPlugin` calls it off the authored
+    // bundle, and `examples/app-todo` and `examples/app-showcase` both ship it.
+    // The first version of this lint told both of them their working handler
+    // registration was "dropped at load".
+    expect(lint({ onEnable: () => {}, functions: { doThing: () => {} } })).toEqual([]);
+  });
+
+  it('still reports `onDisable`, which really does go nowhere', () => {
+    // The distinction the exclusion list has to preserve: `onDisable` is
+    // declared in the protocol but no kernel, runtime or service calls it, so
+    // a value written there IS lost and the author should hear about it.
+    const [finding, ...rest] = lint({ onDisable: () => {} });
+    expect(rest).toEqual([]);
+    expect(finding).toMatchObject({ path: 'stack.onDisable', key: 'onDisable' });
+  });
+
   it('agrees with the injected schema posture instead of asserting its own', () => {
     // Guarding the day `ObjectStackDefinitionSchema` graduates to `.strict()`
     // (ADR-0049 / #4001): the parse becomes loud, and this lint must go quiet
@@ -205,6 +223,18 @@ describe('STACK_KEY_GUIDANCE does not rot', () => {
     }
   });
 
+  it('no runtime member is silently excluded for a key the schema declares', () => {
+    // `functions` legitimately appears in both lists. But if a member ever
+    // exists ONLY here while the schema also declares it and the runtime has
+    // stopped reading it, the exclusion is dead weight hiding a real finding.
+    // Pin the one that carries the exclusion's whole weight instead of trusting
+    // the list's shape: `onEnable` must be excluded AND undeclared.
+    expect(STACK_RUNTIME_MEMBERS).toContain('onEnable');
+    expect(declared, 'onEnable became a declared key — the exclusion is now dead').not.toContain('onEnable');
+    expect(STACK_RUNTIME_MEMBERS, 'onDisable is honoured nowhere; excluding it would hide a real drop')
+      .not.toContain('onDisable');
+  });
+
   it('every entry carries a rename target that exists, or a reason', () => {
     expect(Object.keys(STACK_KEY_GUIDANCE).length).toBeGreaterThan(0);
     for (const [key, hint] of Object.entries(STACK_KEY_GUIDANCE)) {

packages/spec/src/kernel/metadata-authoring-lint.ts

@@ -54,6 +54,7 @@ import {
   FIELD_KEY_GUIDANCE,
   OBJECT_KEY_GUIDANCE,
   STACK_KEY_GUIDANCE,
+  STACK_RUNTIME_MEMBERS,
   type UnknownAuthoringKeyFinding,
 } from '../data/authoring-key-lint';
 import { FieldSchema } from '../data/field.zod';
@@ -256,7 +257,12 @@ export function lintUnknownStackKeys(
   const posture = keyPosture(stackSchema);
   if (!posture || posture.mode !== 'strip' || posture.keys.size === 0) return [];
 
+  // The runtime members are honoured OFF the authored bundle, so the parse
+  // dropping them costs nothing — treating them as declared is what keeps the
+  // lint from calling a working `onEnable` discarded. See STACK_RUNTIME_MEMBERS.
+  const declared = new Set([...posture.keys, ...STACK_RUNTIME_MEMBERS]);
+
   const out: UnknownAuthoringKeyFinding[] = [];
-  lintAuthoredRecordKeys(rawStack, posture.keys, STACK_KEY_GUIDANCE, 'stack', 'stack', out);
+  lintAuthoredRecordKeys(rawStack, declared, STACK_KEY_GUIDANCE, 'stack', 'stack', out);
   return out;
 }