@@ -24,6 +24,7 @@ import { createRequire } from 'node:module';
2424import { fileURLToPath } from 'node:url' ;
2525import { ObjectStackDefinitionSchema } from '@objectstack/spec' ;
2626import { PROTOCOL_MAJOR , PROTOCOL_VERSION } from '@objectstack/spec/kernel' ;
27+ import { MIGRATIONS_BY_MAJOR } from '@objectstack/spec/migrations' ;
2728import { childEnv } from './helpers/serve-process.js' ;
2829
2930const execFileP = promisify ( execFile ) ;
@@ -33,10 +34,19 @@ const TSX = resolve(HERE, '../../../node_modules/.bin/tsx');
3334
3435/**
3536 * A stack authored against protocol 16: every line marked `// 16:` is a shape
36- * the v17 chain must rewrite, spanning each conversion family — renames
37- * (action execute→target, sharing full→edit) and the #3896 close-out removals (rls.priority, the four
38- * tool keys, flow active/template/outputSchema/fallbackNodeId, view/dashboard
39- * inert keys, agent.knowledge, skill.triggerPhrases).
37+ * the v17 chain must rewrite, one per conversion step 17 still registers — the
38+ * sharing-rule `full`→`edit` rename, the flow-node config aliases and lifts,
39+ * the mongo driver alias, the converged retry policy, the page-header subtitle
40+ * alias and the inline action's object-form `params`.
41+ *
42+ * The protocol-16.x conversions (action execute→target, the #3896 close-out
43+ * removals: rls.priority, the four tool keys, flow active/template/
44+ * outputSchema/fallbackNodeId, view/dashboard inert keys, agent.knowledge,
45+ * skill.triggerPhrases) are deliberately NOT here. They aged out with their
46+ * retirement kits (#25767, ADR-0087 2026-10-26 amendment): `--from 16` no
47+ * longer rewrites those shapes, and the strict schema refuses them as unknown
48+ * keys pointing at the protocol upgrade guide, so carrying one would make the
49+ * replayed snapshot invalid by design rather than test the chain.
4050 */
4151const PRE17_CONFIG = `
4252export default {
@@ -51,76 +61,43 @@ export default {
5161 notes: { type: 'textarea', label: 'Notes' },
5262 },
5363 }],
54- actions: [{
55- name: 'close_ticket',
56- label: 'Close',
57- type: 'script',
58- execute: 'closeHandler', // 16: renamed to target
59- shortcut: 'Ctrl+K', // 16: removed (never dispatched)
60- bulkEnabled: true, // 16: removed (toolbar reads view bulkActions)
64+ datasources: [{
65+ name: 'events',
66+ label: 'Events',
67+ driver: 'mongo', // 16: mongo→mongodb
68+ config: { url: 'mongodb://mongo.internal:27017/events' },
6169 }],
6270 flows: [{
6371 name: 'e2e_flow',
6472 label: 'E2E Flow',
6573 type: 'autolaunched',
66- active: false, // 16: removed (status is the lifecycle)
67- template: true, // 16: removed (no reader)
68- // 16: fallbackNodeId removed (fault edges own this). maxRetries is stated
69- // because #4247 refuses a zero-attempt 'retry' — the count is the one v17
70- // flow change the chain surfaces as a semantic TODO instead of rewriting.
71- errorHandling: { strategy: 'retry', maxRetries: 2, fallbackNodeId: 'n9' },
74+ // 16: retryDelayMs→backoffMs. maxRetries is stated because #4247 refuses
75+ // a zero-attempt 'retry' — the count is the one v17 flow change the chain
76+ // surfaces as a semantic TODO instead of rewriting.
77+ errorHandling: { strategy: 'retry', maxRetries: 2, retryDelayMs: 500 },
7278 nodes: [
73- { id: 'n1', type: 'start', label: 'Start', outputSchema: { ok: { type: 'boolean' } } }, // 16: removed
79+ { id: 'n1', type: 'start', label: 'Start' },
7480 { id: 'n2', type: 'delete_record', label: 'Purge', config: { objectName: 'e2e_ticket', filter: { done: true } } }, // canonical since protocol 11 — must pass through untouched
81+ { id: 'n3', type: 'get_record', label: 'Load', config: { object: 'e2e_ticket', filter: { done: false } } }, // 16: object→objectName
82+ { id: 'n4', type: 'notify', label: 'Tell', config: { to: ['{record.owner}'], subject: 'Closed', body: 'Ticket closed.', channels: ['inbox'] } }, // 16: to/subject/body→recipients/title/message
83+ { id: 'n5', type: 'wait', label: 'Pause', config: { duration: 'PT1M' } }, // 16: lifted into waitEventConfig
84+ { id: 'n6', type: 'connector_action', label: 'Post', config: { connectorId: 'slack', actionId: 'chat.postMessage', input: { text: 'done' } } }, // 16: lifted into connectorConfig
85+ { id: 'n7', type: 'map', label: 'Each', config: { collection: '{rows}', flow: 'e2e_child' } }, // 16: flow→flowName
86+ { id: 'n8', type: 'subflow', label: 'Child', config: { flow: 'e2e_child' } }, // 16: flow→flowName
87+ { id: 'n9', type: 'script', label: 'Score', config: { functionName: 'score_ticket', input: { id: '{recordId}' } } }, // 16: functionName/input→function/inputs
7588 ],
7689 edges: [],
7790 }],
78- views: [{
79- object: 'e2e_ticket',
80- list: { type: 'grid', columns: ['title'], responsive: { hiddenOn: ['xs'] }, performance: { lazyLoad: true } }, // 16: removed
81- form: { type: 'simple', sections: [{ fields: ['title'] }], defaultSort: [{ field: 'title' }], aria: { label: 'Ticket' } }, // 16: removed
82- }],
83- dashboards: [{
84- name: 'e2e_kpis',
85- label: 'E2E KPIs',
86- aria: { label: 'KPIs' }, // 16: removed
87- performance: { prefetch: true },// 16: removed
88- widgets: [],
89- }],
90- agents: [{
91- name: 'e2e_agent',
92- label: 'Agent',
93- role: 'Helper',
94- instructions: 'help',
95- knowledge: { sources: ['faq'] }, // 16: removed (never scoped retrieval)
96- }],
97- skills: [{
98- name: 'e2e_skill',
99- label: 'Skill',
100- tools: ['query_records'],
101- triggerPhrases: ['do the thing'], // 16: removed (never matched)
102- }],
103- tools: [{
104- name: 'e2e_tool',
105- label: 'Tool',
106- description: 'A tool',
107- parameters: { type: 'object' },
108- category: 'action', // 16: removed
109- permissions: ['x.y'], // 16: removed (gated nothing)
110- active: true, // 16: removed (withdrew nothing)
111- builtIn: false, // 16: removed
112- }],
113- permissions: [{
114- name: 'e2e_set',
115- label: 'Set',
116- objects: { e2e_ticket: { allowRead: true } },
117- rowLevelSecurity: [{
118- name: 'own_rows',
119- object: 'e2e_ticket',
120- operation: 'select',
121- using: 'owner = current_user.id',
122- enabled: true,
123- priority: 10, // 16: removed (no conflict to order)
91+ pages: [{
92+ name: 'e2e_page',
93+ label: 'E2E Page',
94+ type: 'app',
95+ regions: [{
96+ name: 'header',
97+ components: [
98+ { type: 'page:header', properties: { title: 'Tickets', description: 'All open tickets' } }, // 16: description→subtitle
99+ { type: 'element:button', properties: { label: 'Submit', action: { type: 'api', target: '/api/v1/e2e/submit', method: 'POST', params: { note: 'hi' } } } }, // 16: object-form params→bodyExtra
100+ ],
124101 }],
125102 }],
126103 sharingRules: [{
@@ -135,18 +112,25 @@ export default {
135112};
136113` ;
137114
138- /** Conversion ids the run MUST attribute at least one rewrite to. */
115+ /**
116+ * Conversion ids the run MUST attribute at least one rewrite to: step 17's
117+ * own `conversionIds`, written out so a family leaving the step reds here by
118+ * name (the registry pin in the case below) instead of thinning the fixture's
119+ * coverage in silence.
120+ */
139121const EXPECTED_CONVERSIONS = [
140- 'action-execute-to-target' ,
141- 'action-inert-keys-removed' ,
142- 'flow-inert-keys-removed' ,
143- 'view-inert-keys-removed' ,
144- 'dashboard-inert-keys-removed' ,
145- 'agent-knowledge-removed' ,
146- 'skill-trigger-phrases-removed' ,
147- 'tool-inert-authoring-keys-removed' ,
148- 'permission-rls-priority-removed' ,
149122 'sharing-rule-access-level-full-to-edit' ,
123+ 'flow-node-crud-object-alias' ,
124+ 'flow-node-notify-config-aliases' ,
125+ 'flow-node-wait-event-config-lift' ,
126+ 'flow-node-connector-config-lift' ,
127+ 'flow-node-map-flow-alias' ,
128+ 'flow-node-subflow-flow-alias' ,
129+ 'flow-node-script-config-aliases' ,
130+ 'datasource-driver-mongo-to-mongodb' ,
131+ 'retry-policy-converged' ,
132+ 'page-header-subtitle-alias' ,
133+ 'inline-action-api-params-to-body-extra' ,
150134] ;
151135
152136let dir : string ;
@@ -179,6 +163,11 @@ describe('os migrate meta --from 16 (e2e over the real CLI)', () => {
179163 } ) ;
180164
181165 it ( 'attributes at least one rewrite to every expected v17 conversion family' , ( ) => {
166+ // The list IS step 17's: a conversion that ages out of the step (as the
167+ // 16.x ones did, #25767) or joins it fails here naming the drift, before
168+ // the per-id loop reads it as a missing rewrite.
169+ expect ( [ ...EXPECTED_CONVERSIONS ] . sort ( ) , 'EXPECTED_CONVERSIONS must equal step 17\'s registered conversionIds' )
170+ . toEqual ( [ ...( MIGRATIONS_BY_MAJOR [ 17 ] ?. conversionIds ?? [ ] ) ] . sort ( ) ) ;
182171 const ids = new Set ( out . parsed . applied . map ( ( a : any ) => a . conversionId ) ) ;
183172 for ( const id of EXPECTED_CONVERSIONS ) {
184173 expect ( ids . has ( id ) , `expected a rewrite from ${ id } ; got ${ [ ...ids ] . join ( ', ' ) } ` ) . toBe ( true ) ;
@@ -215,20 +204,26 @@ describe('os migrate meta --from 16 (e2e over the real CLI)', () => {
215204 expect ( parsed . success , JSON . stringify ( parsed . success ? '' : parsed . error . issues . slice ( 0 , 3 ) ) ) . toBe ( true ) ;
216205
217206 // Spot-check one rewrite per family on the snapshot itself.
218- expect ( snap . actions [ 0 ] . target ) . toBe ( 'closeHandler' ) ;
219- expect ( snap . actions [ 0 ] . execute ) . toBeUndefined ( ) ;
220- expect ( snap . actions [ 0 ] . shortcut ) . toBeUndefined ( ) ;
221- expect ( snap . flows [ 0 ] . active ) . toBeUndefined ( ) ;
222- expect ( snap . flows [ 0 ] . errorHandling . fallbackNodeId ) . toBeUndefined ( ) ;
223- expect ( snap . flows [ 0 ] . nodes [ 0 ] . outputSchema ) . toBeUndefined ( ) ;
224- expect ( snap . flows [ 0 ] . nodes [ 1 ] . config . filter , 'canonical key passes through untouched' ) . toEqual ( { done : true } ) ;
225- expect ( snap . views [ 0 ] . list . responsive ) . toBeUndefined ( ) ;
226- expect ( snap . views [ 0 ] . form . defaultSort ) . toBeUndefined ( ) ;
227- expect ( snap . dashboards [ 0 ] . aria ) . toBeUndefined ( ) ;
228- expect ( snap . agents [ 0 ] . knowledge ) . toBeUndefined ( ) ;
229- expect ( snap . skills [ 0 ] . triggerPhrases ) . toBeUndefined ( ) ;
230- expect ( snap . tools [ 0 ] . category ) . toBeUndefined ( ) ;
231- expect ( snap . permissions [ 0 ] . rowLevelSecurity [ 0 ] . priority ) . toBeUndefined ( ) ;
207+ const [ , purge , load , tell , pause , post , each , child , score ] = snap . flows [ 0 ] . nodes ;
208+ expect ( purge . config . filter , 'canonical key passes through untouched' ) . toEqual ( { done : true } ) ;
209+ expect ( load . config . objectName ) . toBe ( 'e2e_ticket' ) ;
210+ expect ( load . config . object ) . toBeUndefined ( ) ;
211+ expect ( tell . config . recipients ) . toEqual ( [ '{record.owner}' ] ) ;
212+ expect ( tell . config . to ) . toBeUndefined ( ) ;
213+ expect ( pause . waitEventConfig . timerDuration ) . toBe ( 'PT1M' ) ;
214+ expect ( post . connectorConfig . connectorId ) . toBe ( 'slack' ) ;
215+ expect ( each . config . flowName ) . toBe ( 'e2e_child' ) ;
216+ expect ( child . config . flowName ) . toBe ( 'e2e_child' ) ;
217+ expect ( score . config . function ) . toBe ( 'score_ticket' ) ;
218+ expect ( score . config . functionName ) . toBeUndefined ( ) ;
219+ expect ( snap . flows [ 0 ] . errorHandling . backoffMs ) . toBe ( 500 ) ;
220+ expect ( snap . flows [ 0 ] . errorHandling . retryDelayMs ) . toBeUndefined ( ) ;
221+ expect ( snap . datasources [ 0 ] . driver ) . toBe ( 'mongodb' ) ;
222+ const [ header , button ] = snap . pages [ 0 ] . regions [ 0 ] . components ;
223+ expect ( header . properties . subtitle ) . toBe ( 'All open tickets' ) ;
224+ expect ( header . properties . description ) . toBeUndefined ( ) ;
225+ expect ( button . properties . action . bodyExtra ) . toEqual ( { note : 'hi' } ) ;
226+ expect ( button . properties . action . params ) . toBeUndefined ( ) ;
232227 expect ( snap . sharingRules [ 0 ] . accessLevel ) . toBe ( 'edit' ) ;
233228 // ⛔ ADR-0113, #16693: the chain does NOT write a column constraint for the
234229 // author. `required: true` crosses 16→17 as the write-time contract and
@@ -358,10 +353,17 @@ describe('os migrate meta --from 16 (e2e over the real CLI)', () => {
358353 * telling the author to run this command.
359354 *
360355 * So the fixture here is deliberately shaped like a real project and not like a
361- * test: `defineStack` at the root, per-artifact helpers imported from a spec
362- * SUBPATH (`@objectstack/spec/ai`, the spelling the example apps use), and the
363- * retired keys authored inside them. A `defineStack`-only tolerance passes the
364- * first and fails the last two.
356+ * test: `defineStack` at the root, per-artifact helpers imported from spec
357+ * SUBPATHS (`@objectstack/spec/ai`, `@objectstack/spec/ui`, the spellings the
358+ * example apps use), and the retired keys authored inside them. A
359+ * `defineStack`-only tolerance passes the first and fails the last two.
360+ *
361+ * The retired keys are ones whose tombstone and conversion still stand
362+ * (`agent.lifecycle`, `dashboard.refreshInterval`; protocol 18, which
363+ * `--from 16` replays into). The fixture used to carry `agent.knowledge` and
364+ * `skill.triggerPhrases`, whose 16.x kits aged out (#25767): their tombstones
365+ * and conversions left the spec, so neither is a retired key any more, only an
366+ * unknown one.
365367 *
366368 * The second test is the other half of the pin, and it is the one that keeps
367369 * this a restoration rather than a widening: `os validate` on the SAME fixture
@@ -379,7 +381,8 @@ describe('os migrate meta over a source carrying a retired key (#9418)', () => {
379381
380382 const RETIRED_KEY_CONFIG = `
381383import { defineStack } from '@objectstack/spec';
382- import { defineAgent, defineSkill } from '@objectstack/spec/ai';
384+ import { defineAgent } from '@objectstack/spec/ai';
385+ import { Dashboard } from '@objectstack/spec/ui';
383386
384387export default defineStack({
385388 manifest: { id: 'com.example.retired-key-e2e', name: 'Retired Key E2E', version: '1.0.0', type: 'app', namespace: 'rk' },
@@ -393,13 +396,13 @@ export default defineStack({
393396 label: 'Agent',
394397 role: 'Helper',
395398 instructions: 'help',
396- knowledge : { sources: ['faq'] }, // RETIRED in protocol 17 — the whole point
399+ lifecycle : { id: 'rk', initial: 'open', states: { open: {} } }, // RETIRED in 17.7.0 — the whole point
397400 })],
398- skills : [defineSkill ({
399- name: 'rk_skill ',
400- label: 'Skill ',
401- tools : ['query_records' ],
402- triggerPhrases: ['do the thing'], // RETIRED in protocol 17
401+ dashboards : [Dashboard.create ({
402+ name: 'rk_ops ',
403+ label: 'Ops ',
404+ widgets : [],
405+ refreshInterval: 300, // RETIRED: renamed to refreshIntervalSeconds
403406 })],
404407});
405408` ;
@@ -434,17 +437,17 @@ export default defineStack({
434437 expect ( parsed . from ) . toBe ( 16 ) ;
435438 // …and through helpers imported from a spec subpath, which is where a
436439 // tolerance scoped to `defineStack` alone would still have refused.
437- expect ( appliedAt . get ( 'agent-knowledge -removed' ) ) . toBe ( 'agents[0].knowledge ' ) ;
438- expect ( appliedAt . get ( 'skill-trigger-phrases-removed ' ) ) . toBe ( 'skills [0].triggerPhrases ' ) ;
440+ expect ( appliedAt . get ( 'agent-lifecycle -removed' ) ) . toBe ( 'agents[0].lifecycle ' ) ;
441+ expect ( appliedAt . get ( 'dashboard-refresh-interval-to-refresh-interval-seconds ' ) ) . toBe ( 'dashboards [0].refreshIntervalSeconds ' ) ;
439442 expect ( parsed . schemaValid ) . toBe ( true ) ;
440443
441444 const snap = JSON . parse ( readFileSync ( join ( rkDir , 'migrated.json' ) , 'utf-8' ) ) ;
442- expect ( snap . agents [ 0 ] . knowledge ) . toBeUndefined ( ) ;
443- expect ( snap . skills [ 0 ] . triggerPhrases ) . toBeUndefined ( ) ;
445+ expect ( snap . agents [ 0 ] . lifecycle ) . toBeUndefined ( ) ;
446+ expect ( snap . dashboards [ 0 ] . refreshInterval ) . toBeUndefined ( ) ;
444447 // The rest of the artifact survives the tolerant load intact — the codemod
445448 // removes what retired, not what it could not parse.
446449 expect ( snap . agents [ 0 ] . name ) . toBe ( 'rk_agent' ) ;
447- expect ( snap . skills [ 0 ] . tools ) . toEqual ( [ 'query_records' ] ) ;
450+ expect ( snap . dashboards [ 0 ] . refreshIntervalSeconds ) . toBe ( 300 ) ;
448451 } , 180_000 ) ;
449452
450453 it ( 'still refuses the same source everywhere else — `os validate` keeps the prescription' , async ( ) => {
@@ -458,8 +461,8 @@ export default defineStack({
458461 } catch ( e : any ) {
459462 refused = true ;
460463 const output = `${ String ( e . stdout ?? '' ) } ${ String ( e . stderr ?? '' ) } ` ;
461- expect ( output ) . toMatch ( / ` a g e n t \. k n o w l e d g e ` w a s r e m o v e d / ) ;
462- expect ( output ) . toMatch ( / o s m i g r a t e m e t a - - f r o m 1 6 / ) ;
464+ expect ( output ) . toMatch ( / ` a g e n t \. l i f e c y c l e ` w a s r e m o v e d / ) ;
465+ expect ( output ) . toMatch ( / o s m i g r a t e m e t a - - f r o m 1 7 / ) ;
463466 }
464467 expect ( refused , '`os validate` must still reject a retired key' ) . toBe ( true ) ;
465468 } , 180_000 ) ;
0 commit comments