feat: RFC-A017 capability I/O schema materialization#418
Open
feat: RFC-A017 capability I/O schema materialization#418
Conversation
added 5 commits
March 4, 2026 19:59
) Replaces the ioSchemaRefs URI-reference pattern with inline capabilitySchemaArtifact objects (target + schema + hash) on every CapabilityIndexEntry, eliminating the indirection gap identified in RFC-A017. Contract changes: - capabilityIndexArtifactVersionSchema bumped 1.0.0 → 1.1.0 - capabilityIoSchemaRefsSchema removed; capabilityIoSchemasSchema added with required input/output/error slots and a reserved optional chunk slot - build-capability-index-snapshot hardcoded version bumped to match Call-site migrations: - extractLocalCapabilities: stub URI refs → unknown-stub schema artifacts (real compilation wired in Phase 3 / #416) - resolve-authoring-completion-item: renders JSON.stringify(schema) for each slot instead of raw URI strings (Phase 4 / #417 will add truncation) - All test fixtures and completion-do golden updated to new shape Closes #413
Adds compileCapabilitySchemas to the spec compiler that converts
domain.capabilities in/out field annotations into deterministic
CompiledJsonSchemaArtifact objects (target + schema + hash).
- New function reads spec.domain.capabilities.<id>.in and .out string
annotation maps, compiles them through the canonical field type
contracts, and returns per-capability { input, output, error } schema
artifact tuples
- error slot always produces the empty strict-object artifact; a future
RFC will introduce spec-level error annotations to populate it
- Exposed via new @gooi/spec-compiler/capability-schemas subpath export
so authoring-diagnostics bootstrap can import without coupling to the
main compile-bundle entrypoint
- Four new tests cover determinism, empty fallbacks, and full annotation
compilation
Closes #414
) Adds optional inputSchema / outputSchema / errorSchema fields to lockedCapabilitySchema so provider publish pipelines can embed inline JSON Schema objects directly in marketplace listing entries. The fields are optional to preserve backward compatibility with legacy listings published before RFC-A017. The CLI/bootstrap threading layer (#416) will use these fields when assembling catalogCapabilities entries for the capability index, falling back to empty-object stubs when the schemas are absent. Closes #415
#416) Connects compileCapabilitySchemas to the bootstrapAuthoringContext pipeline so local capability ioSchemas are derived from real in/out field annotations instead of stub artifacts. Changes: - bootstrapAuthoringContext: calls compileCapabilitySchemas(specSnapshot) and passes the result to extractLocalCapabilities - extractLocalCapabilities: accepts an optional compiledSchemas map; when a capabilityId has a compiled entry, uses its { input, output, error } artifacts; otherwise falls back to the unknown-stub artifacts (preserves backward compat for callers that don't provide schemas) - New test "local capability ioSchemas reflect compiled in/out field annotations" verifies that the hash is not the stub placeholder and field properties are populated correctly after annotation compilation Closes #416
…to completion hover (#417) Introduces a dedicated formatSchemaForHover utility that serializes a JSON Schema object into a compact hover string, truncating at 400 characters with an ellipsis to keep tooltips readable. Updates resolveAuthoringCompletionItem to use formatSchemaForHover for the input/output/error schema lines in completion item documentation, replacing the bare JSON.stringify calls from Phase 1. - format-schema-for-hover.ts: new utility with 400-char truncation limit - resolve-authoring-completion-item.ts: imports and uses formatSchemaForHover - format-schema-for-hover.test.ts: 4 tests covering empty schema, compact rendering, truncation, and the exact-400-char boundary Closes #417
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6383019c45
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+23
to
+24
| "import": "./dist/capability-schemas/compile-capability-schemas.js", | ||
| "default": "./dist/capability-schemas/compile-capability-schemas.js" |
There was a problem hiding this comment.
The new ./capability-schemas export points import/default to ./dist/capability-schemas/compile-capability-schemas.js, but this commit does not add a corresponding bun build output for that file in the package build script. In workspace Bun runs this is masked by the bun condition (src/...), but published/Node consumers that resolve the import condition will hit a missing file at runtime (ERR_MODULE_NOT_FOUND).
Useful? React with 👍 / 👎.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Product Outcome
Capability I/O schemas are now materialized inline on every capability index entry. Authors see the actual JSON shape of a capability's input, output, and error contracts in IDE hover tooltips when writing their spec — no more opaque URI references.
User/Customer Impact
Spec authors get richer, context-aware capability documentation directly in their editor: when they tab-complete a capability name in a
doblock, the hover card shows the real field shapes (e.g.input: {"type":"object","properties":{"message_id":…}}), making it possible to understand a capability's contract without leaving the editor or looking up external docs.Scope Delivered
CapabilityIndexEntry.ioSchemas— replacesioSchemaRefsURI strings with inline{ input, output, error, chunk? }CompiledJsonSchemaArtifactobjects (target + schema + hash); artifact version bumped to 1.1.0 (closes [RFC-A017] Phase 1: Replace ioSchemaRefs with ioSchemas in capability index contract #413)compileCapabilitySchemas— new spec-compiler utility that compilesdomain.capabilities.<id>.in/.outfield annotations into deterministic JSON Schema artifacts via existing canonical field-type machinery; exposed at@gooi/spec-compiler/capability-schemas(closes [RFC-A017] Phase 2: Add compileCapabilitySchemas to spec compiler #414)LockedCapability.inputSchema/outputSchema/errorSchema— optional inline schema fields added to marketplace listing entries so provider publish pipelines can embed schemas at publish time (closes [RFC-A017] Embed capability schemas in marketplace LockedCapability listing entries #415)bootstrapAuthoringContextnow callscompileCapabilitySchemasand passes results toextractLocalCapabilities; local capabilities carry real compiled artifacts instead of stub hashes (closes [RFC-A017] Phase 3: Thread compiled schemas through bootstrap and extractLocalCapabilities #416)formatSchemaForHover— language server utility that serializes a JSON Schema object into a compact hover string, truncating at 400 characters with an ellipsis; wired into completion item hover documentation (closes [RFC-A017] Phase 4: Render capability schema shapes in language server completion hover #417)Out of Scope
chunkschema slot (reserved for streaming capabilities; requires a future spec-level annotation RFC)LockedCapability.inputSchemaat publish timeLockedCapabilityschemas intoBuildCapabilityIndexSnapshotInput.catalogCapabilitiesIssue Link
Closes #413
Closes #414
Closes #415
Closes #416
Closes #417