ecs: let kernels issue commands through helpers (component lists, symbol-keyed values, void helpers)

The three failures come from the kernel subset checks: list resolution for commands.add (the lists.ts module that tracks definitions by file and name), the return <value> requirement for helpers, and the object-literal check on command values. Read subset.md first, then the compiler code behind those three error messages. Done means each repro in the issue builds with kernel: true and produces the same inlined output as the existing numeric and tuple cases.

Summary

A kernel (kernel: true) can't issue a command through a helper unless the helper is written around several compiler limits. Every key is a module-scope Symbol() constant, so in principle the compiler can resolve all of it statically. This asks for the compiler to follow keys through helpers. It is an optimization of the compiler only; no public API changes.

Seen on @adobe/ecs 0.3.0 with Compiler.plugin().

Why it matters: the guidance is that a system that can be a kernel should be one (kernel: true fails the build when its body stops qualifying). Helpers that build "this entity gets these components with these values" are a natural thing to share between systems, and today they push those systems out of the kernel subset.

Minimal repro

keys.ts

export const tag = Symbol();
export const size = Symbol();
export const color = Symbol();
declare module '@adobe/ecs' {
    interface Components {
        [tag]: { type: boolean; default: false };
        [size]: { type: number; default: 1 };
        [color]: { type: number; default: 0 };
    }
}

main.ts

import { System } from '@adobe/ecs';
import { color, size } from './keys.js';
import { dress } from './dress.js';

export const viaHelper = System.create({ kernel: true, components: { with: [size, color] } }, (row, { commands }) => {
    dress(commands, row.entity, row[color]);
});

dress.ts (this is the form that builds, and only because main.ts also imports tag, see 1)

import type { System } from '@adobe/ecs';
import { color, size, tag } from './keys.js';

export const dress = (commands: System.Commands, entity: Parameters<System.Commands['despawn']>[0], c: number): number => {
    commands.add(entity, [size, color, tag], { [size]: 2, [color]: c, [tag]: true });
    return 0;
};

What fails, and what it could do instead

1. The component list is resolved in the kernel's module, not the helper's.

   • With main.ts as above (it doesn't import tag): commands.add: lists name keys by identifiers bound at module scope. The helper's own list is read in the system module's scope, so a key the system module doesn't import fails, even though the helper imports it and the key is a plain top-level Symbol().
   • Naming the list as a constant in the helper's module (const look = [size, color, tag] as const; then commands.add(entity, look, ...)) fails with commands.add: look isn't bound at module scope. subset.md says a list may be "a constant ... in the kernel's module or imported, also through re-exports and namespaces", so I expected this to work.
   • Wanted: resolve a helper's list in the helper's module, then map each key to the definition (the build already tracks definitions by file and name for imported lists, see lists.ts).

2. A helper whose only job is to issue commands must still return <value>. Without the return 0; above: dress must end with return <value>. Wanted: a helper with no result is fine (void).

3. Command values must be written in place as an object literal.

   • commands.add(entity, [size, color, tag], values(c)), where values returns ({ [size]: 2, [color]: c, [tag]: true }) as const, fails with command values must be an object literal like { [position]: value }.
   • A local does too: const values = { [size]: 2, [color]: c, [tag]: true }; fails with struct literals use plain field names.
   • Wanted: allow computed keys that are identifiers of top-level Symbol() constants in a struct literal, track them through locals and helper returns, and match them to the command's list. That is the same resolution as 1 (a key identifier maps to a definition), so a command's values can be assembled by a helper and shared.

Notes

• Everything in 1 to 3 inlines at build time already for numbers, tuples and structs with plain field names, so this extends the same inlining to symbol-keyed structs and component lists.
• With these, helpers like "make this entity a thing with this look" could be shared by several kernel systems instead of copied into each.