Skip to content

Commit 1a2361c

Browse files
feat(service-automation): declared connector instances resolve by (package, name) through the shared resolver (#31725)
<!-- claude-projects-attribution: {"github_login":"os-steve"} --> _Requested by **Steve** · [project thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9B9qYj7GTyDGfaMgXwXx7rZ)_ Part of #31677 Clause-②: no Metadata-protocol: none Narrowing: D3 (a) declared by the card, measured 0 here: no reader in this PR has a caller package (first-party package-caller reads wired: 0), so the closure-outside sub-case of #31527 comment 6728487836 measures 0, sibling-in-the-same-artifact included. Part of epic #31527 (ADR-0150 child E5), connectors only, per seat 3's split on the card (6728849524, epic seat 6728850663). Two remainders of #31677 stay open: - **Webhooks**: waits on the maintainer's ruling on names two packages held before phase 1 (the card's needs-user-decision, Q1). Its code is at `da3bc28e` on this branch's history and lands as its own draft PR after `Ruled:`. - **Email templates**: waits on R2 #31716, which stops the resolver from counting a dependent's added locale (#28802) as a second holder of the base's template name. Card thread `domain:server#3` · `os-steve` · `session_01ADHkmR4astMzES5UkW47jW`; claim 6728454873, file-surface amendment 6728498905. ## 维护者速读 - 改了什么:声明式连接器实例在物化时,按名字取哪一条声明,改为问 R 的共享解析器 `resolvePackageScopedName`(无包调用方):先环境自建项,再全环境唯一的包持有者,否则拒绝并列出全部候选。 - 为什么改:ADR-0150 把连接器改为按(软件包, 名称)寻址;以前两个包同名时只报「名字重复」,不点名是哪两个包。 - 风险与回滚:阶段一的单持有者拒绝对 connector 仍然生效,今天不可能有两个包同名,所以每个名字的答案不变(service-automation 全量 3458 条全绿)。`@objectstack/objectql` 从开发依赖改为运行时依赖,无循环。回滚即还原本 PR。 - 先看:`packages/services/service-automation/src/connector-package-scope.ts`,以及 `plugin.ts` 里 `reconcileDeclaredConnectors` 开头的拒绝循环。 - 两分钟验证:`pnpm --filter @objectstack/service-automation exec vitest run src/connector-materialization.test.ts -t "resolves by"`,预期 2 条通过、其余跳过,其中两个包同名的用例断言启动失败、错误信息点名两个包、工厂从未被调用。 - 需要你做的:无,席位落地。 ## What changes `reconcileDeclaredConnectors` (service-automation, the declared-instance index the engine's `connectors` map is filled from) now asks the ONE package-scoped resolver (`resolvePackageScopedName`, `@objectstack/objectql`, R #31637) which declared connector instance a name means, before it materializes anything. The reconcile reads the whole environment's declaration and has no caller package, so it asks as a caller with no package (ADR-0150 D3): the environment's own item, else the unique package holder, else a refusal naming every candidate. | Reader on `main`, by symbol | Pick today | Caller package | After this PR | |:--|:--|:--|:--| | `reconcileDeclaredConnectors` desired map | a second entry refused as "duplicate", no candidates named | none | a name the resolver refuses is not materialized; `fail()` names every candidate (fatal at boot for a host-declared entry, soft for a stored one, as the duplicate check already was) | Not touched, and why: - `connector_action`'s `connectorConfig.connectorId` is the one reference here written inside a package (the flow's). `AutomationContext` (spec) names no flow package, so the node cannot ask as that package yet; per seat 3's ruling (Q3 A) it stays context-free here and is wired after E1 #31672. It keeps reading the engine's one-instance-per-name map, which this PR now fills through the resolver. - `findInertDeclaredConnectors` (an audit warning) picks no item. - Plugin-registered connectors (`engine.registerConnector`) are no registry items; the resolver answers not-found and they keep ADR-0097 §4's one-origin rule. - Stored references (`sys_connector_connection.connector_name`) are S3 #31684's. `@objectstack/objectql` moves from `devDependencies` to `dependencies` in service-automation (claim amendment 6728498905). No cycle: objectql's workspace closure (deps, devDeps and peers, 14 packages) does not contain service-automation. E1 #31672 makes the same move on the same lines; a trial merge of its branch onto this head is clean, and per the seat E1 lands first and this branch merges `origin/main` after it. ## ADR-0150's four readings - **(a) phase-1 one-holder tests stay green.** objectql's four `registry-bare-name-one-holder*` suites plus `package-scoped-resolver.test.ts`: 187 passed; the four `bare-name-one-holder*` dogfood files are in the targeted run below. This PR does not touch objectql. - **(b) bare-name behaviour unchanged for every name with one holder.** The new suite pins the one-holder case on a real `SchemaRegistry` (the connector materializes with the holder's definition), and service-automation's full suite stays green. No URL, MCP or SDK surface moves. - **(c) no migration.** Nothing stored is read or written differently. - **(d)** `Clause-②: no`, `Metadata-protocol: none`; no ADR-0087 entry. ## Tests `service-automation/src/connector-materialization.test.ts`, new describe "a declared connector name resolves by (package, name)": one holder materializes; two holders fail the boot naming both, and the provider factory is never called. The harness's `boot()` gains an optional `schemaRegistry` (a real registry in place of the double). No existing test changed. Ablation (`scripts/ablation-replace.mjs`, mutation proved on disk, restored to the HEAD blob, `git diff HEAD` empty after; the suite imports `src`, so no `dist` leg; measured at `da3bc28e`, whose service-automation tree is byte-identical to this head): `refusedConnectorNames` records no refusal → 1 failed: the boot still fails on the older duplicate-name check, but `expected '[Automation] duplicate declarative co…' to contain 'connector instance \'billing\' is not…'`. The candidates are what the pin adds. ## Verification (head 47f5d0c) - `@objectstack/service-automation` test exit 0 (266 files, 3458 tests); typecheck exit 0; root `eslint --no-inline-config packages/services/service-automation` exit 0 (the package has no `lint` script). Run under `os-verify-lock`. - Targeted dogfood after `turbo run build --filter='@objectstack/dogfood^...'` (70/70): 19 files (the four phase-1 bare-name families, email template boot/materialization/locale files, connector install/restart/package-ref files, declarative MCP, webhook materialization), 96 tests passed. - Derived gates: `dispatch-gates --commands` derived 85 families at 47f5d0c; all 85 run with `exit 0`; `--ran`: "85 derived, 85 run, 0 NOT-MEASURED, 0 UNRUN" (a derived zero, every row carrying its exit code). - `test:repo` not run locally (CI's `Test Core`); this diff touches no repo-project test. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01ADHkmR4astMzES5UkW47jW --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 470339e commit 1a2361c

6 files changed

Lines changed: 158 additions & 5 deletions

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@objectstack/service-automation': patch
3+
---
4+
5+
feat: a declared connector instance's name resolves by (package, name) through the shared package-scoped resolver (ADR-0150 D3/D4)
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
Which declared connector instance a name materializes is now answered by `resolvePackageScopedName` from `@objectstack/objectql`, never by list order. The connector reconcile reads the whole environment's declaration, so it asks as a caller with no package: the environment's own item, else the unique package holder, else a refusal that names every candidate.
11+
12+
Who is affected: nobody today. Phase 1's one-holder refusal still holds for `connector`, so no two installed packages can ship the same connector instance name, and every name resolves exactly as before. Once that backstop narrows (its own later release), a name two packages ship is not materialized, and boot fails naming both packages, as it already did for a duplicate instance name (which named no candidates).
13+
14+
`@objectstack/service-automation` now depends on `@objectstack/objectql` at runtime (it was a dev dependency).

‎packages/services/service-automation/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
"@objectstack/formula": "workspace:*",
3131
"@objectstack/metadata-core": "workspace:*",
3232
"@objectstack/metadata-protocol": "workspace:*",
33+
"@objectstack/objectql": "workspace:*",
3334
"@objectstack/platform-objects": "workspace:*",
3435
"@objectstack/plugin-auth": "workspace:*",
3536
"@objectstack/spec": "workspace:*",
@@ -38,7 +39,6 @@
3839
"devDependencies": {
3940
"@objectstack/driver-sql": "workspace:*",
4041
"@objectstack/metadata-core": "workspace:*",
41-
"@objectstack/objectql": "workspace:*",
4242
"@objectstack/plugin-audit": "workspace:*",
4343
"@objectstack/plugin-security": "workspace:*",
4444
"@objectstack/plugin-sharing": "workspace:*",

‎packages/services/service-automation/src/connector-materialization.test.ts‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ import {
2929
type CredentialResolver,
3030
} from './plugin.js';
3131
import type { AutomationEngine } from './engine.js';
32+
import { SchemaRegistry } from '@objectstack/objectql';
3233
import { computeAliyunAcs3Signature } from './request-signing/aliyun-acs3-hmac-sha256.js';
3334
import { computeAlipayV3Signature, readAlipayPrivateKey } from './request-signing/alipay-v3.js';
3435

@@ -109,6 +110,11 @@ interface BootOptions {
109110
registered?: unknown[];
110111
/** Collects every `logger.error` record the boot writes (#28594: the soft path's record). */
111112
logged?: Array<{ msg: string; meta?: unknown }>;
113+
/**
114+
* A real `SchemaRegistry` to serve as the objectql registry instead of the
115+
* double over `declared` (ADR-0150 E5: the package-scoped resolver reads it).
116+
*/
117+
schemaRegistry?: SchemaRegistry;
112118
}
113119

114120
/** `SchemaRegistry.getArtifactItem('connector', name, packageId)` over `registered` (#28594). */
@@ -136,7 +142,7 @@ async function boot(declared: unknown[], opts: BootOptions = {}): Promise<LiteKe
136142
dependencies: ['com.objectstack.service-automation'],
137143
async init(ctx: any) {
138144
ctx.registerService('objectql', {
139-
registry: {
145+
registry: opts.schemaRegistry ?? {
140146
listItems: (type: string) => (type === 'connector' ? declared : []),
141147
getPackage: (id: string) => opts.packages?.[id],
142148
getArtifactItem: artifactReader(opts.registered),
@@ -418,6 +424,40 @@ describe('ADR-0097 — declarative connector materialization', () => {
418424
});
419425
});
420426

427+
describe('ADR-0150 D3 — a declared connector name resolves by (package, name) (epic #31527 child E5)', () => {
428+
const A = 'com.acme.billing_a';
429+
const B = 'com.acme.billing_b';
430+
/** A real registry: each id installed as a code package, each shipping `billing` in its own composite slot. */
431+
function registryShipping(...packageIds: string[]): SchemaRegistry {
432+
const registry = new SchemaRegistry();
433+
registry.logLevel = 'silent';
434+
for (const id of packageIds) {
435+
registry.installPackage({ id, name: id, version: '1.0.0', type: 'app', namespace: id.split('.').pop() } as never, 'code');
436+
registry.registerItem('connector', providerConnector('billing', { label: `billing from ${id}` }), 'name' as never, id);
437+
}
438+
return registry;
439+
}
440+
441+
it('one package holder: the instance materializes, as before', async () => {
442+
const { factory, calls } = makeFakeProvider();
443+
const kernel = await boot([], { providerFactory: factory, schemaRegistry: registryShipping(A) });
444+
expect(automationOf(kernel).getRegisteredConnectors()).toContain('billing');
445+
expect(calls.map((c) => c.label)).toEqual([`billing from ${A}`]);
446+
});
447+
448+
it('two package holders: the boot refuses, naming both — no instance is picked by list order', async () => {
449+
const { factory, calls } = makeFakeProvider();
450+
const err = await boot([], { providerFactory: factory, schemaRegistry: registryShipping(A, B) }).then(
451+
() => undefined,
452+
(e: Error) => e,
453+
);
454+
expect(err?.message).toContain(`connector instance 'billing' is not materialized`);
455+
expect(err?.message).toContain(`"${A}"`);
456+
expect(err?.message).toContain(`"${B}"`);
457+
expect(calls).toEqual([]);
458+
});
459+
});
460+
421461
describe('ADR-0097 — runtime re-materialization on metadata:reloaded (F1)', () => {
422462
it('materializes an instance published after boot', async () => {
423463
const { factory, calls } = makeClosableProvider();
Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* [ADR-0150 D3/D4, epic #31527 child E5] Which declared connector instance a
5+
* name means — answered by the ONE package-scoped resolver
6+
* (`resolvePackageScopedName`, `@objectstack/objectql`), never by list order.
7+
*
8+
* A connector is addressed by `(package, name)`. The engine keeps one live
9+
* instance per name, and the reconcile that materializes declared instances
10+
* is context-free: it reads the whole environment's declaration, so it asks
11+
* as a caller with no package — the environment's own item, else the unique
12+
* package holder, else a refusal naming every candidate. A refused name is not
13+
* materialized: the reconcile reports the refusal (the boot fails loudly on a
14+
* host-declared entry, as it does for a duplicate name) and tears down what
15+
* it materialized before, so no flow dispatches to one of the candidates on a
16+
* guess. Every other answer leaves the name to the reconcile as it stood.
17+
*
18+
* While phase 1's one-holder refusal stands (`connector` is one of its types)
19+
* no two packages hold a connector name, so this refuses nothing on a booted
20+
* deployment; it is the reader the type's trailing backstop child (ADR-0150
21+
* D9) narrows that refusal behind.
22+
*
23+
* A connector a plugin registers in code (`engine.registerConnector`) is no
24+
* registry item: the resolver answers not-found for it, and it keeps the
25+
* engine's own ADR-0097 §4 one-origin rule.
26+
*/
27+
28+
import {
29+
resolvePackageScopedName,
30+
type PackageScopedRefusal,
31+
type PackageScopedRegistry,
32+
} from '@objectstack/objectql';
33+
34+
/** The registry, when it carries the slice the package-scoped resolver reads. */
35+
export function packageScopedRegistryOf(registry: unknown): PackageScopedRegistry | undefined {
36+
const r = registry as Partial<Record<keyof PackageScopedRegistry, unknown>> | null | undefined;
37+
return typeof r?.packageScopedHoldersOf === 'function'
38+
&& typeof r.getPackageScopedItem === 'function'
39+
&& typeof r.getEnvironmentScopedItem === 'function'
40+
&& typeof r.getPackage === 'function'
41+
&& typeof r.getAllPackages === 'function'
42+
? (registry as PackageScopedRegistry)
43+
: undefined;
44+
}
45+
46+
/**
47+
* The refusal of every declared connector name in `names` that resolves to no
48+
* single holder (ADR-0150 D3, a caller with no package), keyed by name. A name
49+
* the resolver answers — or does not hold at all — is absent.
50+
*/
51+
export function refusedConnectorNames(
52+
registry: PackageScopedRegistry,
53+
names: Iterable<string>,
54+
): Map<string, PackageScopedRefusal> {
55+
const refused = new Map<string, PackageScopedRefusal>();
56+
for (const name of new Set(names)) {
57+
const resolved = resolvePackageScopedName(registry, { type: 'connector', name });
58+
if (resolved.status === 'refused') refused.set(name, resolved);
59+
}
60+
return refused;
61+
}

‎packages/services/service-automation/src/plugin.ts‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,8 @@ import {
6868
} from './connector-credentials.js';
6969
import { CONNECTOR_CREDENTIAL_SOURCE_SERVICE } from '@objectstack/types';
7070
import { createConnectorCredentialSource } from './connector-credential-source.js';
71+
import { packageScopedRegistryOf, refusedConnectorNames } from './connector-package-scope.js';
72+
import type { PackageScopedRefusal, PackageScopedRegistry } from '@objectstack/objectql';
7173
import { createConnectorRequestSigner } from './request-signing/index.js';
7274
import { ConnectorConnectionStore, type ConnectorConnectionRecord } from './connector-connections.js';
7375
import {
@@ -2586,6 +2588,31 @@ export class AutomationServicePlugin implements Plugin {
25862588
this.reloadedConnectors = { items, owners };
25872589
}
25882590

2591+
/**
2592+
* [ADR-0150 D3] The refusal of every enabled provider-bound declared
2593+
* connector name that resolves to no single holder, read over the ObjectQL
2594+
* registry ({@link refusedConnectorNames}). A composition with no registry
2595+
* has no package coordinate to resolve against, and refuses nothing here.
2596+
*/
2597+
private refusedDeclaredConnectorNames(ctx: PluginContext, declared: readonly unknown[]): Map<string, PackageScopedRefusal> {
2598+
let registry: PackageScopedRegistry | undefined;
2599+
try {
2600+
registry = packageScopedRegistryOf(ctx.getService<{ registry?: unknown }>('objectql')?.registry);
2601+
} catch {
2602+
registry = undefined; // no registry service
2603+
}
2604+
if (!registry) return new Map();
2605+
const names: string[] = [];
2606+
for (const raw of declared) {
2607+
const entry = raw as DeclaredConnectorItem;
2608+
if (typeof entry?.name !== 'string' || entry.name.length === 0) continue;
2609+
if (typeof entry.provider !== 'string' || entry.provider.length === 0) continue;
2610+
if (entry.enabled === false) continue;
2611+
names.push(entry.name);
2612+
}
2613+
return refusedConnectorNames(registry, names);
2614+
}
2615+
25892616
/**
25902617
* [#28534] The readers {@link nonHostDeclaringPackageOf} judges a
25912618
* connector entry's origin with, off the `objectql` engine the declared
@@ -2893,6 +2920,16 @@ export class AutomationServicePlugin implements Plugin {
28932920
ctx.logger.error(msg, undefined, cause === undefined ? undefined : describeThrownForLog(cause));
28942921
};
28952922

2923+
// [ADR-0150 D3, epic #31527 child E5] A declared name that resolves to
2924+
// no single holder (two packages declare it) is refused, naming every
2925+
// candidate, and never materialized: no instance is picked by list
2926+
// order ({@link refusedConnectorNames}).
2927+
const refusedNames = this.refusedDeclaredConnectorNames(ctx, declared);
2928+
for (const [name, refusal] of refusedNames) {
2929+
const stored = declared.some((raw) => (raw as DeclaredConnectorItem)?.name === name && storedEntry(raw));
2930+
fail(`[Automation] connector instance '${name}' is not materialized: ${refusal.message}`, undefined, stored);
2931+
}
2932+
28962933
// Build the desired set: enabled provider-bound instances, keyed by name.
28972934
// A descriptor (no `provider`) or an `enabled: false` instance is not
28982935
// desired — if we materialized it before, it is torn down below.
@@ -2903,6 +2940,7 @@ export class AutomationServicePlugin implements Plugin {
29032940
if (typeof entry.provider !== 'string' || entry.provider.length === 0) continue;
29042941
const bound = entry as DeclaredConnectorItem & { name: string; provider: string };
29052942
if (bound.enabled === false) continue;
2943+
if (refusedNames.has(bound.name)) continue;
29062944
// [#28713] Held until every plugin has started ({@link holdStoredEntries}).
29072945
if (this.holdStoredEntries && storedEntry(bound)) {
29082946
this.storedEntriesHeld = true;

‎pnpm-lock.yaml‎

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)