Typert generator never recognizes @Remote from an npm-installed protocol, so an out-of-tree plugin gets no Remote layer at all

[szsip239]

Summary

The Typert generator never recognizes @Remote in a plugin that installs @deepseek-ai/dsh-typert-protocol from npm, so no invocations are generated and the plugin has no Remote layer at all. Declaring ./remote on top of that fails the build outright.

This sits one layer earlier than #1993 and #2091. Those describe a runtime module-identity split, where the markers exist but the gateway reads the wrong copy. Here the markers are never turned into descriptors in the first place, so an out-of-tree plugin cannot reach the runtime problem those threads describe.

Everything below is measured against published 0.1.0-rc.6 packages.

Where it fails

WorkspaceAnalyzer.isTypeMetaSymbol() in packages/typert/generator/src/analyzer.ts — the decorator is accepted only when one of two things holds. (Both checks below are byte-identical in the published lib/index.js of 0.1.0-rc.6, not just in the source tree.)

const registration = this.registrationForFile(declaration.getSourceFile().fileName)
if (registration?.name === '@deepseek-ai/dsh-typert-protocol') return true
for (let current: ts.Node | undefined = declaration; current !== undefined; current = optionalParent(current)) {
  if (ts.isModuleDeclaration(current)
    && ts.isStringLiteral(current.name)
    && current.name.text === '@deepseek-ai/dsh-typert-protocol') return true
}
return false

An npm-installed protocol satisfies neither:

Branch 1 — registration. Registrations come from loadRegistrations(), which walks the face aggregates' project references and keeps only paths under <root>/packages/:

if (!isWithin(realPath(packageRoot), join(this.options.root, 'packages'))) continue

A package resolved from node_modules is never a registration, so registrationForFile() returns undefined.

Branch 2 — ambient module block. The published .d.ts declares Remote as an ordinary module export, with no ambient wrapper:

$ grep -c 'declare module' @deepseek-ai/dsh-typert-protocol/lib/types/index.d.ts
0
$ grep -n 'export declare function Remote' .../index.d.ts
80:export declare function Remote<This extends object, ...>(...): void;
86:export declare function Remote(exportName: string): RemoteMethodDecorator;

So the ancestor walk finds no matching ModuleDeclaration either.

Reproduction

A third-party package that otherwise satisfies every discovery requirement — it sits under <root>/packages/, is referenced from tsconfig.host.json, and declares its service through a declare module '@deepseek-ai/cordis' Context merge:

import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'

declare module '@deepseek-ai/cordis' {
  interface Context { mosaicBoard: MosaicBoardService }
}

export class MosaicBoardService extends TypertRemoteService {
  constructor(ctx: Context) { super(ctx, 'mosaicBoard') }

  @Remote('state')
  state(): Promise<BoardStatePayload> { /* … */ }
}

Observed with WorkspaceTypertGenerator:

Step	Result
discover()	finds the package (faces: ['host'])
analyze()	service model present (services: ['mosaicBoard']), invocations: []
generate() with ./remote declared	throws typert(host): <pkg> publishes Remote artifacts but has no Remote methods
generate() with ./remote removed	succeeds; lib/typert.host.js carries the service, method signatures and payload type declarations, with invocations: []

The generated artifact is internally consistent about it — the printed signature keeps the decorator text while the descriptor list stays empty:

"members": [ { "kind": "method", "name": "state",
               "signature": "@Remote('state') state(): Promise<BoardStatePayload>" } ]
…
invocations: [
],

So the failure is silent in the direction that matters: a package without a ./remote export builds green and simply has no RPC.

Notes on what is not the blocker

Two things looked like blockers while narrowing this down and turned out not to be, in case they save someone else the detour:

• ctx.remote.$mount(contribution) is public. The fixed first-party import list in @deepseek-ai/dsh-api-remotes/src/client/index.ts is that assembly's own selection, not a gate — a third-party client half can mount its own generated contribution.
• The dual-face bootstrap cycle is avoidable. A single package whose client face imports the typert.remote-client.js this run generates deadlocks the generator's typecheck. First-party code sidesteps it by splitting host and client into separate packages; a single dual-face package can pass generate(undefined, ['host']) and analyze only the contributing face.

Possible fixes

Either would be enough, and they are not exclusive:

1. Widen the origin check so a declaration whose containing package manifest is named @deepseek-ai/dsh-typert-protocol is accepted, regardless of whether it is a workspace registration. This keeps the intent — only the real protocol's Remote counts — while allowing an installed copy.
2. Ship an ambient declaration from the protocol package, which makes branch 2 match for consumers without changing the generator.

Given #1993 and #2091, (1) alone still leaves an out-of-tree plugin's Remote layer broken at runtime under the source launcher, so the compile-time and runtime halves probably want to land together to make third-party Remote actually usable.

Environment

• @deepseek-ai/dsh-typert-generator@0.1.0-rc.6, @deepseek-ai/dsh-typert-protocol@0.1.0-rc.6
• Plugin consumes DSH 0.1.0-rc.6; dsh-testkit@0.3.1 green for the same plugin's non-Remote surface (service + two tools)
• macOS, Node 24.13, pnpm 10.28

[sophon2000]

Confirmed independently: the same defect is still present in 0.1.1-rc.2 and in official master commit b150a551b8.

I encountered it while integrating an out-of-tree DSH plugin. TypeScript resolves Remote, RemoteScope, and TypertRemoteService from the installed @deepseek-ai/dsh-typert-protocol, but isTypeMetaSymbol() still accepts only workspace registrations or ambient-module declarations. A temporary consumer-side paths redirect to an ambient declaration makes generation work, which isolates the failure to LIB metadata identity.

I prepared a narrow patch here:

sophon2000@7804432

The patch:

• reuses the generator's existing externalModuleIdentityForFile() helper;
• accepts declarations only when the resolved external package is exactly @deepseek-ai/dsh-typert-protocol;
• keeps same-named decorators from a lookalike package rejected;
• does not register node_modules as workspace packages or expand external declarations into the Typert type graph;
• preserves both existing workspace-registration and ambient-module paths.

Regression coverage includes a positive installed-package case and a negative same-named lookalike-package case. Validation completed on the patch branch:

• remote-model.spec.ts: 40/40 passed;
• documentation sync tests: 28/28 passed;
• full lint/build passed;
• bilingual documentation pairing and pre-commit checks passed.

The direct regression fixture uses a regular node_modules layout. The reused resolver also handles pnpm's nested .pnpm/.../node_modules/<package> physical paths by selecting the last node_modules segment, although a dedicated nested-layout regression test could still be added if desired.

Since the contribution guide currently does not accept external pull requests, please feel free to cherry-pick or adapt the commit. I can also prepare a PR if maintainers later invite one.

[sophon2000]

0.1.2-alpha.1 follow-up

I retested this against the official dsh-v0.1.2-alpha.1 tag at cd5ef8148158. The installed-protocol identity gap is still present: declarations resolved from an npm-style node_modules/@deepseek-ai/dsh-typert-protocol package are not accepted by isTypeMetaSymbol(), so an out-of-tree Remote package still produces no Remote layer without the narrow identity fix.

I ported the fix onto the exact alpha.1 tag and kept the original rc.2 branch unchanged for traceability:

• alpha.1 branch: fix/typert-external-protocol-identity-alpha1
• source fix: f0568ddd64
• branch tip, including the alpha.1 stream fixture alignment: 16eb74a971

Fresh validation on the independent alpha.1 topic branch:

• remote-model.spec.ts: 40/40 passed;
• Typert generator TypeScript project build passed;
• repository pre-push full Host build and Client contracts typecheck passed.

I also generated the official alpha.1 release shape locally with build:official plus release:pack --family dsh (241 tarballs), applied the exact package patch to both published generator execution faces, and verified it in an out-of-tree Video Harness consumer: 342/342 consumer tests, 2/2 real DSH-to-Python cross-process tests, 3/3 PostgreSQL persistence scenarios, and Profile add/doctor/start/login/remove all passed.

The alpha.1 packages are still not available from npm, so this is source and locally packed release-shape evidence, not a claim that a registry package has been fixed or published.

[me93-ghb]

I hit the same behavior in an out-of-tree Harness bundle with the generator and protocol pinned to 0.1.1-rc.2. The analyzer discovers the package and service but returns invocations: []; generation then fails with publishes Remote artifacts but has no Remote methods. The imported symbols resolve from the published protocol declarations under node_modules, matching the ownership path described here.