@@ -0,0 +1,17 @@
+---
+'@objectstack/objectql': patch
+'@objectstack/runtime': patch
+---
+
+feat(objectql, runtime): the action engine keeps each package's handler under one object and action name (ADR-0150 D4)
+
+Clause-②: no (narrowing)
+Metadata-protocol: none
+
+<!-- adr-0087: not-required (no-migration-prescription) nothing is retired or renamed and no stored or authored shape changes: the new package-keyed resolution is reached only by a caller that names its package, which no door does yet, so there is nothing for `objectstack migrate meta` to rewrite -->
+
+Two packages can now each register a handler for the same object and action name, and both are kept. `ObjectQL#executeAction(objectName, actionName, ctx, { packageId })` runs that package's own handler. With no `packageId` it runs exactly what it ran before: the last registration under `OBJECT:NAME`, with the replacement still warned and naming both packages.
+
+The router (`resolveRouteActionDeclaration`) takes an optional `callerPackageId`. Given one, it resolves the bare action name through the package-scoped resolver (ADR-0150 D3) over the `action` items that belong to the routed object: the caller's own declaration first, then the one holder in its declared closure. Two holders in the closure, or a holder outside it (another package, or an environment-authored action), is refused with every candidate named, and the `/actions` door answers 409 `RESOURCE_CONFLICT`. No door passes a caller's package yet, so every request today resolves and runs exactly as before.
+
+New exports from `@objectstack/objectql`: `resolveActionByPackage`, `actionOwnerScopedRegistry`, `actionHolderCoordinate`, `actionHandlerCoordinate`, `ENVIRONMENT_ACTION_COORDINATE`, and the types `ActionPackageQuery` and `ExecuteActionOptions`.
@@ -0,0 +1,66 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [ADR-0150 D4, #31673] The package coordinate of an action HANDLER — the
+ * package half of the engine's `(package, objectName, name)` key, read off the
+ * owner label a handler is registered under. Its own module, free of the
+ * package-scoped resolver, because the engine (`engine-actions.ts`) is part of
+ * the lean `./core` entry, which never imports `@objectstack/metadata-protocol`
+ * (ADR-0076 D2). The declaration half is `action-package-addressing.ts`.
+ */
+
+import { handlerOwnerPackageId } from './bare-name-one-holder.js';
+
+/**
+ * The environment's own slot (ADR-0150 D1 bucket 4): the handlers the engine
+ * plugin's authored-action resync registers (`metadata-service`) for
+ * environment-authored rows whose name no code package ships. A resolved
+ * environment holder (`actionHolderCoordinate`) dispatches here.
+ */
+export const ENVIRONMENT_ACTION_COORDINATE = '';
+
+/**
+ * [#31673, review 6729902179 F1] The slot of a handler registered with NO
+ * owner: host code calling `engine.registerAction(object, name, fn)` (the
+ * documented pattern a code package's target-bound actions use, e.g.
+ * `examples/app-todo`). Kept apart from {@link ENVIRONMENT_ACTION_COORDINATE}
+ * so a package call can reach host code without ever reaching an
+ * environment-authored action's body. Not a package id: a manifest id is
+ * reverse-domain and never parenthesised.
+ */
+export const HOST_ACTION_COORDINATE = '(host)';
+
+/** The owner label the engine plugin's authored-action resync registers under. */
+const AUTHORED_ACTION_OWNER = 'metadata-service';
+
+/**
+ * The package coordinate of a handler registered under `owner` (the
+ * `packageName` argument of `ObjectQL#registerAction`):
+ *
+ *  - `app:<packageId>` (the runtime's `bindAppArtifactHandlers`) → that package;
+ *  - `metadata-service` → {@link ENVIRONMENT_ACTION_COORDINATE}: an
+ *    environment-authored action (the resync binds no row a code package
+ *    ships, `isArtifactShippedAction`, except a declared override, which is
+ *    bound at its base's coordinate instead);
+ *  - none or `''` → {@link HOST_ACTION_COORDINATE}: host code;
+ *  - any other owner (a plugin's id) → itself, as the one-holder rule names it
+ *    ({@link handlerOwnerPackageId}).
+ */
+export function actionHandlerCoordinate(owner: string | undefined): string {
+  if (owner === AUTHORED_ACTION_OWNER) return ENVIRONMENT_ACTION_COORDINATE;
+  if (owner === undefined || owner === '') return HOST_ACTION_COORDINATE;
+  return handlerOwnerPackageId(owner);
+}
+
+/**
+ * [#31673] Is a handler at `coordinate`, registered under `owner`, one a call
+ * naming a package with no handler of its own may fall back to? Host code
+ * ({@link HOST_ACTION_COORDINATE}) and a plugin's handler are; a package's
+ * (`app:<id>`) and the environment's ({@link ENVIRONMENT_ACTION_COORDINATE})
+ * never are: those belong to another holder's declarations.
+ */
+export function isSharedHandlerCoordinate(coordinate: string, owner: string | undefined): boolean {
+  if (coordinate === HOST_ACTION_COORDINATE) return true;
+  if (coordinate === ENVIRONMENT_ACTION_COORDINATE || owner === undefined) return false;
+  return handlerOwnerPackageId(owner) === owner;
+}
@@ -0,0 +1,181 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The action's `(package, objectName, name)` key (ADR-0150 D4) — #31673, child
+ * E2 of epic #31527: the declaration half, R's resolver over the `action`
+ * items that own one object ({@link resolveActionByPackage}), and the handler
+ * half's coordinate ({@link actionHandlerCoordinate}).
+ *
+ * The registry is the real `SchemaRegistry`, as R's own suite builds it:
+ * packages through `installPackage` (their manifests are the declared closure),
+ * items through `registerItem` under each package's composite slot.
+ *
+ * The negative pins (`refuses`, `never`) were each ablated once — the refused
+ * behaviour put back, the pin read red, restored — and the readings are in the
+ * PR body, not kept as test files.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SchemaRegistry } from './registry.js';
+import { resolveActionByPackage, actionHolderCoordinate } from './action-package-addressing.js';
+import { actionHandlerCoordinate, ENVIRONMENT_ACTION_COORDINATE, HOST_ACTION_COORDINATE } from './action-handler-coordinate.js';
+import { resolvePackageScopedName, type PackageScopedResolution } from './package-scoped-resolver.js';
+
+const A = 'com.acme.alpha';
+const B = 'com.acme.beta';
+const P = 'com.acme.caller';
+
+const manifest = (id: string, deps: string[] = []) => ({
+  id, name: id, version: '1.0.0', type: 'app', namespace: id.split('.').pop()!,
+  ...(deps.length > 0 ? { dependencies: Object.fromEntries(deps.map((d) => [d, '^1.0.0'])) } : {}),
+}) as never;
+
+let registry: SchemaRegistry;
+const install = (id: string, deps: string[] = []) => registry.installPackage(manifest(id, deps), 'code');
+
+/** A package's action `name`, bound to `objectName` (or object-less), labelled by its package. */
+const ship = (name: string, packageId: string, objectName?: string) =>
+  registry.registerItem('action', {
+    name, label: `${packageId.split('.').pop()} ${objectName ?? 'global'}`, type: 'script',
+    body: { language: 'js', source: 'return 1;', capabilities: [] },
+    ...(objectName ? { objectName } : {}),
+  }, 'name' as never, packageId);
+
+/** An environment-authored action (no package), as `sys_metadata` hydration registers it. */
+const authored = (name: string, objectName?: string) =>
+  registry.registerItem('action', {
+    name, label: `env ${objectName ?? 'global'}`, type: 'script',
+    body: { language: 'js', source: 'return 1;', capabilities: [] },
+    ...(objectName ? { objectName } : {}), _provenance: 'org',
+  }, 'name' as never);
+
+const label = (r: PackageScopedResolution): string | undefined =>
+  r.status === 'resolved' ? (r.item as { label?: string }).label : undefined;
+
+const resolve = (objectName: string | undefined, actionName: string, callerPackageId?: string | null) =>
+  resolveActionByPackage(registry, { objectName, actionName, callerPackageId });
+
+beforeEach(() => {
+  registry = new SchemaRegistry();
+  registry.logLevel = 'silent';
+});
+
+describe('ADR-0150 D4 — an object-bound action is keyed (package, objectName, name)', () => {
+  it('two packages\' same-named actions on two objects never meet: each object resolves its own holder', () => {
+    install(A);
+    install(B);
+    ship('approve', A, 'account');
+    ship('approve', B, 'lead');
+    // Control: R alone, on the registry's (type, name) key, sees two holders.
+    expect(resolvePackageScopedName(registry, { type: 'action', name: 'approve' })).toMatchObject({ status: 'refused' });
+    expect(label(resolve('account', 'approve'))).toBe('alpha account');
+    expect(label(resolve('lead', 'approve'))).toBe('beta lead');
+    // A's caller asks for `lead`: A's `account` action is not a candidate; B's is outside A's closure.
+    expect(resolve('lead', 'approve', A)).toMatchObject({
+      status: 'refused', reason: 'outside-closure', candidates: [{ kind: 'package', packageId: B }],
+    });
+    expect(label(resolve('account', 'approve', A))).toBe('alpha account');
+  });
+
+  it('a caller of package P resolves its own action on the object before a closure holder\'s', () => {
+    install(A);
+    install(P, [A]);
+    ship('approve', A, 'account');
+    ship('approve', P, 'account');
+    const r = resolve('account', 'approve', P);
+    expect(r).toMatchObject({ status: 'resolved', via: 'own', holder: { kind: 'package', packageId: P } });
+    expect(label(r)).toBe('caller account');
+  });
+
+  it('refuses a caller whose closure holds the name on the object twice, naming both holders', () => {
+    install(A);
+    install(B);
+    install(P, [A, B]);
+    ship('approve', A, 'account');
+    ship('approve', B, 'account');
+    const r = resolve('account', 'approve', P);
+    expect(r).toMatchObject({ status: 'refused', reason: 'ambiguous-in-closure' });
+    if (r.status !== 'refused') throw new Error('unreachable');
+    expect(r.candidates).toEqual([{ kind: 'package', packageId: A }, { kind: 'package', packageId: B }]);
+    for (const id of [A, B]) expect(r.message).toContain(id);
+  });
+
+  it('D3 (a) — refuses a package caller whose only holder on the object is an environment-authored action, naming the environment', () => {
+    install(P);
+    authored('approve', 'account');
+    const r = resolve('account', 'approve', P);
+    expect(r).toMatchObject({ status: 'refused', reason: 'outside-closure', candidates: [{ kind: 'environment' }] });
+  });
+
+  it('D3 (a) control — the same environment-authored action resolves for a caller with no package', () => {
+    install(P);
+    authored('approve', 'account');
+    expect(resolve('account', 'approve')).toMatchObject({ status: 'resolved', via: 'environment', holder: { kind: 'environment' } });
+  });
+
+  it('refuses a package caller whose only holder is a package outside its closure, naming it — never served', () => {
+    install(A);
+    install(P);
+    ship('approve', A, 'account');
+    expect(resolve('account', 'approve', P)).toMatchObject({
+      status: 'refused', reason: 'outside-closure', candidates: [{ kind: 'package', packageId: A }],
+    });
+  });
+
+  it('falls to the object-less holders only when no holder is bound to the object, in the router\'s order', () => {
+    install(A);
+    install(B);
+    install(P, [A, B]);
+    ship('approve', A); // object-less
+    expect(label(resolve('account', 'approve', P))).toBe('alpha global');
+    ship('approve', B, 'account');
+    expect(label(resolve('account', 'approve', P))).toBe('beta account');
+  });
+
+  it('a refusal on the object never falls through to an object-less holder', () => {
+    install(A);
+    install(B);
+    install(P, [A, B]);
+    ship('approve', A, 'account');
+    ship('approve', B, 'account');
+    registry.registerItem('action', { name: 'approve', label: 'caller global', type: 'script', body: { language: 'js', source: 'return 1;', capabilities: [] } }, 'name' as never, P);
+    expect(resolve('account', 'approve', P)).toMatchObject({ status: 'refused', reason: 'ambiguous-in-closure' });
+  });
+
+  it('an object-less route resolves among the object-less holders only', () => {
+    install(A);
+    install(P, [A]);
+    ship('approve', A, 'account');
+    expect(resolve('global', 'approve', P)).toEqual({ status: 'not-found' });
+    ship('approve', P);
+    expect(label(resolve('global', 'approve', P))).toBe('caller global');
+  });
+
+  it('one holder of the name answers the same item R\'s own read answers (phase-1 parity, reading (b))', () => {
+    install(A);
+    ship('approve', A, 'account');
+    const r = resolve('account', 'approve');
+    const direct = resolvePackageScopedName(registry, { type: 'action', name: 'approve' });
+    expect(r).toEqual(direct);
+    expect(r.status === 'resolved' ? actionHolderCoordinate(r) : undefined).toBe(A);
+  });
+});
+
+describe('ADR-0150 D4 — the coordinate a handler is registered under', () => {
+  it('reads a package\'s handler owner `app:ID` as that package, a plugin id as itself', () => {
+    expect(actionHandlerCoordinate(`app:${A}`)).toBe(A);
+    expect(actionHandlerCoordinate('com.objectstack.plugin.auth')).toBe('com.objectstack.plugin.auth');
+  });
+
+  it('reads the authored-action resync as the environment\'s slot, and no owner as host code\'s — two slots', () => {
+    expect(actionHandlerCoordinate('metadata-service')).toBe(ENVIRONMENT_ACTION_COORDINATE);
+    for (const owner of [undefined, '']) expect(actionHandlerCoordinate(owner)).toBe(HOST_ACTION_COORDINATE);
+    expect(HOST_ACTION_COORDINATE).not.toBe(ENVIRONMENT_ACTION_COORDINATE);
+  });
+
+  it('an environment holder resolves to the environment\'s coordinate', () => {
+    authored('approve', 'account');
+    const r = resolve('account', 'approve');
+    expect(r.status === 'resolved' ? actionHolderCoordinate(r) : 'x').toBe(ENVIRONMENT_ACTION_COORDINATE);
+  });
+});
@@ -0,0 +1,110 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * # An action is addressed by `(package, objectName, name)` (ADR-0150 D4, child E2)
+ *
+ * ADR-0150 D4 re-keys the action engine from `objectName:name` to
+ * `(package, objectName, name)`, object-less actions under
+ * `(package, global, name)`. This module holds the two halves of that key that
+ * the engine (`engine-actions.ts`) and the router
+ * (`@objectstack/runtime`'s `resolveRouteActionDeclaration`) share:
+ *
+ *  - **the handler's coordinate** (`actionHandlerCoordinate`, in
+ *    `action-handler-coordinate.ts` so the lean `./core` entry the engine
+ *    belongs to never reaches the resolver's `@objectstack/metadata-protocol`
+ *    import, ADR-0076 D2): which package a registered handler belongs to;
+ *  - **the declaration's holder** ({@link resolveActionByPackage}): which
+ *    package's declaration a caller of package P means by a bare action name
+ *    on an object, resolved by the ONE rule (ADR-0150 D3,
+ *    {@link resolvePackageScopedName}) over the registry's `action` items that
+ *    own that object.
+ *
+ * ⛔ It does not re-implement the rule. R's resolver keys the registry's
+ * `(type, name)`, which is the object-less action's whole identity and leaves
+ * the object-bound key to this child (its module doc). So the object half is
+ * a VIEW of the registry ({@link actionOwnerScopedRegistry}): the same five
+ * reads, answering only the items whose owner key
+ * ({@link standaloneActionOwnerKey}, the router's own test) is the routed
+ * object. Two packages' `approve` on two objects are then two names that never
+ * meet, and the steps, the closure and the refusals are R's.
+ */
+
+import { GLOBAL_ACTION_OBJECT_KEY, isObjectLessActionKey, standaloneActionOwnerKey } from './action-governance.js';
+import { ENVIRONMENT_ACTION_COORDINATE } from './action-handler-coordinate.js';
+import {
+  resolvePackageScopedName,
+  type PackageScopedRegistry,
+  type PackageScopedResolution,
+} from './package-scoped-resolver.js';
+
+/**
+ * The registry, seen through one owner key: the `action` items of each holder
+ * whose owner key is `ownerKey` (an object's name, or the object-less
+ * {@link GLOBAL_ACTION_OBJECT_KEY}), and nothing else. Every other type, and
+ * the package reads, pass through unchanged.
+ */
+export function actionOwnerScopedRegistry(registry: PackageScopedRegistry, ownerKey: string): PackageScopedRegistry {
+  const objectLess = isObjectLessActionKey(ownerKey);
+  const owns = (item: unknown): boolean => {
+    if (item === null || item === undefined || typeof item !== 'object') return false;
+    const owner = standaloneActionOwnerKey(item);
+    return objectLess ? isObjectLessActionKey(owner) : owner === ownerKey;
+  };
+  return {
+    getPackage: (id) => registry.getPackage(id),
+    getAllPackages: () => registry.getAllPackages(),
+    packageScopedHoldersOf: (type, name) => {
+      const holders = registry.packageScopedHoldersOf(type, name);
+      if (type !== 'action') return holders;
+      return holders.filter((packageId) => owns(registry.getPackageScopedItem(type, name, packageId)));
+    },
+    getPackageScopedItem: <T>(type: string, name: string, packageId: string, member?: string) => {
+      const item = registry.getPackageScopedItem<T>(type, name, packageId, member);
+      return type !== 'action' || owns(item) ? item : undefined;
+    },
+    getEnvironmentScopedItem: <T>(type: string, name: string, member?: string) => {
+      const item = registry.getEnvironmentScopedItem<T>(type, name, member);
+      return type !== 'action' || owns(item) ? item : undefined;
+    },
+  };
+}
+
+/** What {@link resolveActionByPackage} is asked. */
+export interface ActionPackageQuery {
+  /** The routed object, or the object-less key (`global`, legacy `*`, none). */
+  readonly objectName: string | undefined;
+  /** The action's declarative name. */
+  readonly actionName: string;
+  /** The caller's package; omitted or `null` for a caller with no package. */
+  readonly callerPackageId?: string | null;
+}
+
+/**
+ * Which package's declaration `actionName` on `objectName` means to the
+ * caller (ADR-0150 D3 over the D4 key): first among the declarations bound to
+ * the routed object, then — when none is — among the object-less ones, the
+ * order the router reaches a handler in (`actionHandlerObjectKeys`: the object
+ * first, then `global`). A refusal of the first step is the answer; it never
+ * falls through to the object-less holders.
+ */
+export function resolveActionByPackage<T = unknown>(
+  registry: PackageScopedRegistry,
+  query: ActionPackageQuery,
+): PackageScopedResolution<T> {
+  const ask = (ownerKey: string) => resolvePackageScopedName<T>(actionOwnerScopedRegistry(registry, ownerKey), {
+    type: 'action',
+    name: query.actionName,
+    callerPackageId: query.callerPackageId ?? null,
+  });
+  if (isObjectLessActionKey(query.objectName)) return ask(GLOBAL_ACTION_OBJECT_KEY);
+  const bound = ask(query.objectName as string);
+  return bound.status === 'not-found' ? ask(GLOBAL_ACTION_OBJECT_KEY) : bound;
+}
+
+/**
+ * The handler coordinate a resolution's holder registers under: a package
+ * holder's package, the environment's own item the environment's slot.
+ */
+export function actionHolderCoordinate(resolution: Extract<PackageScopedResolution, { status: 'resolved' }>): string {
+  return resolution.holder.kind === 'package' ? resolution.holder.packageId : ENVIRONMENT_ACTION_COORDINATE;
+}