feat(grpc): Convert takes the id form, as sysml -id does (#732)

[someshSandbox]

Fixes #732.

ConvertRequest.id_form chooses how derived element ids are spelled when notation is written as a graph, as sysml -id does:

id_form	package P { part def A; part a : A; } → api-json, @id of P::a
unset or "qualified"	P__a (as before)
"uuid"	a name-based uuid, byte-identical to sysml -convert api-json -id uuid
"guid", or any value with a sysml target	INVALID_ARGUMENT, as -id refuses them

It applies to inline content, a file, and a model_hash parsed from several documents.

Change:

• sysml.proto: string id_form = 7; on ConvertRequest. The stubs are regenerated with the pinned generators (make proto-buf, proto-ts, python-proto, proto-rust): Go, Java, TypeScript, Python and Rust, plus the Rust descriptor. Each diff adds only the field and the re-encoded descriptor.
• internal/frontend/grpc/export.go:
  • convertOptions reads id_form with export.ParseIDForm, under the rules cmd/sysml's convertOptions applies to -id.
  • The single-document path passes it through convert.ConvertWith/ConvertTolerantWith, and the several-document path through export.ModelToRDFWith.
• docs/guide/07-saving-and-rdf.md documents the field.

Tests:

• internal/frontend/grpc/convert_id_form_test.go:
  • for "", qualified and uuid, the service's output is byte-identical to convert.ConvertWith under that form;
  • a model of two documents gets uuid ids under uuid;
  • a notation target and an unknown value are INVALID_ARGUMENT.
• make proto-lint and make proto-breaking pass (a field added, nothing removed or renumbered).
• internal/frontend/grpc/..., tests/grpc/... and internal/translate/convert/... pass. TestOccupiedPortExitsNonzero in cmd/sysml-grpc fails the same way on develop locally.

client/node's package.json and package-lock.json are out of sync on develop (the @openmbee/opensysml-sysml-grpc-* optional dependencies aren't in the lock), so npm ci refuses. The TypeScript stub was generated with @bufbuild/protoc-gen-es 2.14.0, the pinned version, installed apart. The lock is left as it is.

🤖 Generated with Claude Code

---

[devin-ai-integration]

Devin Review found 1 potential issue.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

[devin-ai-integration]

🟡 Wrong status for invalid id form

For a multi-document model targeting notation, id_form returns FAILED_PRECONDITION instead of INVALID_ARGUMENT. The target check runs before convertOptions, so clients receive the wrong status for an invalid field.

Learn more

A cached model parsed from several documents takes a separate conversion path. That path rejects a notation target with FAILED_PRECONDITION before validating the new id_form field. The field's API contract requires INVALID_ARGUMENT when it is supplied for a direction other than notation-to-graph. This affects requests specifying both an invalid id_form direction and an unsupported multi-document output.

Example: Parse two documents, then call Convert with their model_hash, to_format: "sysml", and id_form: "uuid". The call returns FAILED_PRECONDITION for the notation target; the id_form contract requires INVALID_ARGUMENT.

Recommended fix: Validate nonempty req.IdForm against the parsed target with convertOptions before the multi-document target restriction in convertModelOfDocuments, while preserving FAILED_PRECONDITION when id_form is empty.

---

Was this helpful? React with 👍 or 👎 to provide feedback.