Found while answering the UI session's question about schema_json during the channel-settings reshape (092194cd).
EVIDENCE
Definition.Schema is a Go string (internal/app/controlplane/registry.go:19), passed straight through to the descriptor: pb.ResourceDescriptor{Kind: d.Kind, Title: d.Title, SchemaJson: d.Schema, ...} (:30). Every definition in the catalogue sets one of exactly two package constants (internal/app/controlplane/definitions.go):
So no resource descriptor carries properties, titles, descriptions, formats, or bounds. Nothing derives the schema from the document types either: the wire types carry only json tags, and no code reflects over them.
CONSEQUENCE
internal/webui's ControlPlaneResourceCard renders per-field metadata from schema properties (property.description, and a schema title superseding its hardcoded label map). With no properties in any schema those paths are dead for every control-plane resource, so operators get Go-derived or underscore-split labels and no explanation of what an editable field means -- which is exactly what made the channel-settings defects visible in the first place (a field reading "Window" asking for a nanosecond count).
It also blocks two small, already-agreed UI improvements: a duration placeholder for rate_limit.window (needs format: duration) and a description for rate_limit.max_requests (0 disables rate limiting).
FIX DIRECTION
Give each definition a real properties schema. Two shapes, and the choice is a design decision rather than a mechanic:
Hand-written per resource, next to the document type it describes. Smallest change; drifts from the document when a field is added, so it wants a guard test comparing schema properties against the document type's json tags -- the shape TestToolSettingsProjectionCarriesEveryMCPServerField already uses for MCPServer.
Derived by reflection from the document type (json tags for keys, Go types for type/format, a struct tag for prose). One source of truth, no drift, but it is a small framework and every resource's prose moves into struct tags.
Whichever lands, the UI side needs one answer first: whether ControlPlaneResourceCard iterates the schema's properties or the document's keys. If it iterates properties, a partial schema silently hides fields from operators, so the schema must be complete per resource from the first commit.
First instance to fix, in the same window: channel-settings (archie-core-02rm, reshape committed as 092194cd), then container-runtime-policies (archie-core-q4og), which has the same untagged-projection problem and would reuse the same schema.
Notes
FIX COMMITTED, GATE PENDING: a19cd24b 'feat(controlplane): derive resource schemas from the documents they describe'.
Sam ruled the wire-or-delete fork in the wire direction, and the UI session's second finding settled the shape: derive the types, author no prose. Definition now names its document type (Document any, replacing the Schema string) and Definition.Descriptor derives the schema from it -- json tags for keys, falling back to the Go field name because that is what encoding/json stores, with the Go type giving type/format and a field's own title/format/doc tags overriding. A duration derives as {"type":"string","format":"duration"}, so every duration field in the catalogue (poll_interval, max_uptime, rate_limit.window, container lifetime) gets an affordance from one rule rather than one per resource.
Prose deliberately not authored: internal/webui/config_schema.go is already the single home for field descriptions (Label/Description/Type/Options per dotted config path, 226 lines), and a second home is the duplication this repo legislates against. required is never emitted, since an empty string is legitimate for nearly every field here.
Guarded by TestEveryResourceDescriptorDerivesProperties, which walks the catalogue NewServer builds (the constructor production uses) and fails if any kind describes no fields -- the assertion that would have caught all twelve bare constants. It accepts additionalProperties for keyed-collection documents, because a map document has no fixed keys by design.
Left open until the merge train's full task check passes on a19cd24b; the author's scoped suite, vet, build, lint and docs:check are green.
Remaining consumer half is NOT in this commit: the value-driven StructuredResourceCard/StructuredValueEditor still ignores the schema (the only component that parsed one, ControlPlaneResourceCard, has zero references and is dead). The UI session holds the read-side change and is now unblocked; the dead component's fate is Sam's call.
Close reason
Fixed: a19cd24b (ancestor of current HEAD) names Definition's document type so the schema descriptor derives field metadata from it rather than bare type constants; the control-plane definitions carry Document and the Web UI renders from the descriptor.
Imported from beads archie-core-2xs6 · GitHub #1170 · type task · priority P3 · created 2026-09-21 · closed 2026-09-29
Found while answering the UI session's question about schema_json during the channel-settings reshape (092194cd).
EVIDENCE
Definition.Schema is a Go string (internal/app/controlplane/registry.go:19), passed straight through to the descriptor: pb.ResourceDescriptor{Kind: d.Kind, Title: d.Title, SchemaJson: d.Schema, ...} (:30). Every definition in the catalogue sets one of exactly two package constants (internal/app/controlplane/definitions.go):
objectSchema = {"type":"object"}
arraySchema = {"type":"array"}
So no resource descriptor carries properties, titles, descriptions, formats, or bounds. Nothing derives the schema from the document types either: the wire types carry only json tags, and no code reflects over them.
CONSEQUENCE
internal/webui's ControlPlaneResourceCard renders per-field metadata from schema properties (property.description, and a schema title superseding its hardcoded label map). With no properties in any schema those paths are dead for every control-plane resource, so operators get Go-derived or underscore-split labels and no explanation of what an editable field means -- which is exactly what made the channel-settings defects visible in the first place (a field reading "Window" asking for a nanosecond count).
It also blocks two small, already-agreed UI improvements: a duration placeholder for rate_limit.window (needs format: duration) and a description for rate_limit.max_requests (0 disables rate limiting).
FIX DIRECTION
Give each definition a real properties schema. Two shapes, and the choice is a design decision rather than a mechanic:
1. Hand-written per resource, next to the document type it describes. Smallest change; drifts from the document when a field is added, so it wants a guard test comparing schema properties against the document type's json tags -- the shape TestToolSettingsProjectionCarriesEveryMCPServerField already uses for MCPServer.
2. Derived by reflection from the document type (json tags for keys, Go types for type/format, a struct tag for prose). One source of truth, no drift, but it is a small framework and every resource's prose moves into struct tags.
Whichever lands, the UI side needs one answer first: whether ControlPlaneResourceCard iterates the schema's properties or the document's keys. If it iterates properties, a partial schema silently hides fields from operators, so the schema must be complete per resource from the first commit.
First instance to fix, in the same window: channel-settings (archie-core-02rm, reshape committed as 092194cd), then container-runtime-policies (archie-core-q4og), which has the same untagged-projection problem and would reuse the same schema.
### Notes
FIX COMMITTED, GATE PENDING: a19cd24b 'feat(controlplane): derive resource schemas from the documents they describe'.
Sam ruled the wire-or-delete fork in the wire direction, and the UI session's second finding settled the shape: derive the types, author no prose. Definition now names its document type (Document any, replacing the Schema string) and Definition.Descriptor derives the schema from it -- json tags for keys, falling back to the Go field name because that is what encoding/json stores, with the Go type giving type/format and a field's own title/format/doc tags overriding. A duration derives as {"type":"string","format":"duration"}, so every duration field in the catalogue (poll_interval, max_uptime, rate_limit.window, container lifetime) gets an affordance from one rule rather than one per resource.
Prose deliberately not authored: internal/webui/config_schema.go is already the single home for field descriptions (Label/Description/Type/Options per dotted config path, 226 lines), and a second home is the duplication this repo legislates against. required is never emitted, since an empty string is legitimate for nearly every field here.
Guarded by TestEveryResourceDescriptorDerivesProperties, which walks the catalogue NewServer builds (the constructor production uses) and fails if any kind describes no fields -- the assertion that would have caught all twelve bare constants. It accepts additionalProperties for keyed-collection documents, because a map document has no fixed keys by design.
Left open until the merge train's full task check passes on a19cd24b; the author's scoped suite, vet, build, lint and docs:check are green.
Remaining consumer half is NOT in this commit: the value-driven StructuredResourceCard/StructuredValueEditor still ignores the schema (the only component that parsed one, ControlPlaneResourceCard, has zero references and is dead). The UI session holds the read-side change and is now unblocked; the dead component's fate is Sam's call.
### Close reason
Fixed: a19cd24b (ancestor of current HEAD) names Definition's document type so the schema descriptor derives field metadata from it rather than bare type constants; the control-plane definitions carry Document and the Web UI renders from the descriptor.
---
_Imported from beads `archie-core-2xs6` · GitHub #1170 · type task · priority P3 · created 2026-09-21 · closed 2026-09-29_
sam
added the lowtask labels 2026-10-27 13:38:44 +00:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Found while answering the UI session's question about schema_json during the channel-settings reshape (
092194cd).EVIDENCE
Definition.Schema is a Go string (internal/app/controlplane/registry.go:19), passed straight through to the descriptor: pb.ResourceDescriptor{Kind: d.Kind, Title: d.Title, SchemaJson: d.Schema, ...} (:30). Every definition in the catalogue sets one of exactly two package constants (internal/app/controlplane/definitions.go):
objectSchema = {"type":"object"}
arraySchema = {"type":"array"}
So no resource descriptor carries properties, titles, descriptions, formats, or bounds. Nothing derives the schema from the document types either: the wire types carry only json tags, and no code reflects over them.
CONSEQUENCE
internal/webui's ControlPlaneResourceCard renders per-field metadata from schema properties (property.description, and a schema title superseding its hardcoded label map). With no properties in any schema those paths are dead for every control-plane resource, so operators get Go-derived or underscore-split labels and no explanation of what an editable field means -- which is exactly what made the channel-settings defects visible in the first place (a field reading "Window" asking for a nanosecond count).
It also blocks two small, already-agreed UI improvements: a duration placeholder for rate_limit.window (needs format: duration) and a description for rate_limit.max_requests (0 disables rate limiting).
FIX DIRECTION
Give each definition a real properties schema. Two shapes, and the choice is a design decision rather than a mechanic:
Whichever lands, the UI side needs one answer first: whether ControlPlaneResourceCard iterates the schema's properties or the document's keys. If it iterates properties, a partial schema silently hides fields from operators, so the schema must be complete per resource from the first commit.
First instance to fix, in the same window: channel-settings (archie-core-02rm, reshape committed as
092194cd), then container-runtime-policies (archie-core-q4og), which has the same untagged-projection problem and would reuse the same schema.Notes
FIX COMMITTED, GATE PENDING:
a19cd24b'feat(controlplane): derive resource schemas from the documents they describe'.Sam ruled the wire-or-delete fork in the wire direction, and the UI session's second finding settled the shape: derive the types, author no prose. Definition now names its document type (Document any, replacing the Schema string) and Definition.Descriptor derives the schema from it -- json tags for keys, falling back to the Go field name because that is what encoding/json stores, with the Go type giving type/format and a field's own title/format/doc tags overriding. A duration derives as {"type":"string","format":"duration"}, so every duration field in the catalogue (poll_interval, max_uptime, rate_limit.window, container lifetime) gets an affordance from one rule rather than one per resource.
Prose deliberately not authored: internal/webui/config_schema.go is already the single home for field descriptions (Label/Description/Type/Options per dotted config path, 226 lines), and a second home is the duplication this repo legislates against. required is never emitted, since an empty string is legitimate for nearly every field here.
Guarded by TestEveryResourceDescriptorDerivesProperties, which walks the catalogue NewServer builds (the constructor production uses) and fails if any kind describes no fields -- the assertion that would have caught all twelve bare constants. It accepts additionalProperties for keyed-collection documents, because a map document has no fixed keys by design.
Left open until the merge train's full task check passes on a19cd24b; the author's scoped suite, vet, build, lint and docs:check are green.
Remaining consumer half is NOT in this commit: the value-driven StructuredResourceCard/StructuredValueEditor still ignores the schema (the only component that parsed one, ControlPlaneResourceCard, has zero references and is dead). The UI session holds the read-side change and is now unblocked; the dead component's fate is Sam's call.
Close reason
Fixed:
a19cd24b(ancestor of current HEAD) names Definition's document type so the schema descriptor derives field metadata from it rather than bare type constants; the control-plane definitions carry Document and the Web UI renders from the descriptor.Imported from beads
archie-core-2xs6· GitHub #1170 · type task · priority P3 · created 2026-09-21 · closed 2026-09-29