coilyco-flight-deck/umbra

Watch

Add typed bounded repeatable inline query fields #260

New issue

Closed

opened 2026-07-26 00:38:26 +00:00 by coilyco-ops · 3 comments

coilyco-ops commented

2026-07-26 00:38:26 +00:00

Member

Goal

Extend the frozen inline HTTP grammar so guarded MCP consumers can describe query parameters with their real types, numeric bounds, and repeated array encoding.

Discovered by QA for coilyco-bridge/deploy#218

Problem

Flat query "name" entries intentionally lower to strings. Discord API v10 needs integer pagination, boolean filters, and repeated array parameters. The current opcore.Args.Query map[string]string and ward-mcp bridge collapse every supplied value to one scalar, so the generated tool schema and wire request are inaccurate.

Proposed contract

Keep flat query declarations backward compatible. Add a query block using the existing body-field vocabulary where it fits:

query {
    field "limit" type="integer" minimum=1 maximum=100
    field "pinned" type="boolean"
    array "channel_id" items="string" min-items=1 max-items=25
}

The exact property spelling may follow the repository's KDL conventions, but the resulting descriptor and JSON Schema must preserve type and bounds.

Acceptance

Existing flat query lists and query aliases remain byte-for-byte compatible.
Query blocks accept scalar string, boolean, integer, and number fields plus scalar arrays.
Unknown nodes, properties, unsupported types, duplicate names, impossible bounds, and object query values fail closed.
JSON Schema emits minimum, maximum, minItems, and maxItems when declared.
Request assembly validates bounds and array lengths before any upstream call.
Array query inputs serialize as repeated keys in declaration/input order.
Scalar query inputs retain existing encoding and alias behavior.
URL-bound policy validation runs on every repeated value.
opcore exposes a consumer-compatible Args shape without forcing existing scalar consumers to rewrite.
Focused parser, schema, request, alias, fail-closed, and regression tests pass.
The inline grammar docs, FEATURES inventory, and generated godoc surface are updated.

This is a generic engine capability. No Discord-specific names or defaults belong in cli-guard.

## Goal Extend the frozen inline HTTP grammar so guarded MCP consumers can describe query parameters with their real types, numeric bounds, and repeated array encoding. Discovered by QA for https://forgejo.coilysiren.me/coilyco-bridge/deploy/issues/218 ## Problem Flat `query "name"` entries intentionally lower to strings. Discord API v10 needs integer pagination, boolean filters, and repeated array parameters. The current `opcore.Args.Query map[string]string` and ward-mcp bridge collapse every supplied value to one scalar, so the generated tool schema and wire request are inaccurate. ## Proposed contract Keep flat query declarations backward compatible. Add a query block using the existing body-field vocabulary where it fits: ```kdl query { field "limit" type="integer" minimum=1 maximum=100 field "pinned" type="boolean" array "channel_id" items="string" min-items=1 max-items=25 } ``` The exact property spelling may follow the repository's KDL conventions, but the resulting descriptor and JSON Schema must preserve type and bounds. ## Acceptance * Existing flat query lists and query aliases remain byte-for-byte compatible. * Query blocks accept scalar string, boolean, integer, and number fields plus scalar arrays. * Unknown nodes, properties, unsupported types, duplicate names, impossible bounds, and object query values fail closed. * JSON Schema emits `minimum`, `maximum`, `minItems`, and `maxItems` when declared. * Request assembly validates bounds and array lengths before any upstream call. * Array query inputs serialize as repeated keys in declaration/input order. * Scalar query inputs retain existing encoding and alias behavior. * URL-bound policy validation runs on every repeated value. * opcore exposes a consumer-compatible Args shape without forcing existing scalar consumers to rewrite. * Focused parser, schema, request, alias, fail-closed, and regression tests pass. * The inline grammar docs, FEATURES inventory, and generated godoc surface are updated. This is a generic engine capability. No Discord-specific names or defaults belong in cli-guard.

coilyco-ops referenced this issue from coilyco-flight-deck/mcp-beaver

2026-07-26 00:45:26 +00:00

Project typed repeated query inputs through MCP #33

coilyco-ops commented

2026-07-26 01:08:12 +00:00

Author

Member

QA extended the generic acceptance contract: inline query fields also need an at-most-one declaration for cases such as cursor alternatives. The implementation uses mutually-exclusive "a" "b" ... inside query { ... }, resolves every member against local query names, enforces the group before any upstream call, and emits standard draft-07 pairwise allOf constraints using not plus required. Typed arrays continue to encode as repeated keys in input order.

QA extended the generic acceptance contract: inline query fields also need an at-most-one declaration for cases such as cursor alternatives. The implementation uses `mutually-exclusive "a" "b" ...` inside `query { ... }`, resolves every member against local query names, enforces the group before any upstream call, and emits standard draft-07 pairwise `allOf` constraints using `not` plus `required`. Typed arrays continue to encode as repeated keys in input order.

coilyco-ops referenced this issue from a commit

2026-07-26 01:09:24 +00:00

feat(opcore): add typed query contracts

coilyco-ops commented

2026-07-26 01:09:47 +00:00

Author

Member

Implementation checkpoint is pushed on feat/typed-query-260 at 91378ee38c9ab084678e778f9e7980ade1f2e617.

Validation: focused opcore and specverb query tests pass, make build, make vet, make tidy, the godoc check, and GOOS=linux make lint pass. All-files pre-commit passes the task files and reports only the pre-existing 81-line README catalog-cap failure. The native Windows full suite also reports existing Unix path, mode, HOME, and shell assumptions outside this change.

Implementation checkpoint is pushed on `feat/typed-query-260` at `91378ee38c9ab084678e778f9e7980ade1f2e617`. Validation: focused opcore and specverb query tests pass, `make build`, `make vet`, `make tidy`, the godoc check, and `GOOS=linux make lint` pass. All-files pre-commit passes the task files and reports only the pre-existing 81-line README catalog-cap failure. The native Windows full suite also reports existing Unix path, mode, HOME, and shell assumptions outside this change.

coilyco-ops commented

2026-07-26 01:10:10 +00:00

Author

Member

Correction to the checkpoint comment: the exact pushed SHA is 91378ee6bb7d3f259fbe4473a7d7c4ef77750b2a.

Correction to the checkpoint comment: the exact pushed SHA is `91378ee6bb7d3f259fbe4473a7d7c4ef77750b2a`.

coilyco-ops referenced this issue from a commit

2026-07-26 02:06:15 +00:00

fix(specverb): enforce typed query contracts

coilyco-ops closed this issue

2026-07-26 02:11:09 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilyco-flight-deck/umbra#260

No description provided.

Rows
Columns