docs: ADR-0037 refinement (behavior-based subtype test + @kind charter) + generalized decision docs#128
Merged
Conversation
…charter Generalizes the vocabulary-expansion framework so it transfers to ANY future decision, not just the cases that prompted it: - The guiding question is SEMANTIC BEHAVIOR, not surface storage: ask what X DOES, not whether it's a string. - Subtype test is now behavioral: a concept is a subtype if it has its own native type OR behavior OR attributes (the extension point for custom logic) — not merely 'distinct native type'. - @kind chartered as the ONE structural-variant-within-a-subtype axis (source table/view, uri url/urn); never a catch-all, never on a plain string, never swallowing native-type-distinct concepts / boolean flags / validation. - The 'string formats' set splits by behavior: url/uri→field.uri, ip→field.inet (native types + behavior), only email/hostname→@stringformat (plain validated strings); uuid was already field.uuid. ADR-0036 decision #2 updated to the split (uri/inet subtypes + @stringformat email/hostname). CLAUDE.md Design Judgment updated. Agent-context decision docs generalized in a follow-on commit on this branch. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GF9xLEQZaPus5Y6opk398n
… (ADR-0037)
Replace the field-specific "choosing the right field shape" guidance with a
general, mechanical decision procedure an LLM can re-derive for ANY concept —
not a lookup table of specific answers.
The guiding question is semantic behavior, not surface storage ("what does X
do?", never "is X a string/number/date?"). The ordered routing from ADR-0037:
(0) derivable -> derive, add nothing; (1) physical-only -> @dbColumnType escape
hatch; (2a) own native type/behavior/attributes -> subtype; (2b) structural
variant within a subtype -> @kind; (2c) modifies/validates/configures -> attribute.
Adds the self-documentation-over-economy and no-same-name-overload corollaries,
a compact decision table, and an ADR-0037 authority pointer.
Examples use only currently-registered vocab (field.uuid/currency/decimal,
source.rdb @kind, template.output @kind, @localTime, @maxLength/@precision) so
the capability-grounding + drift gates stay green; the general rule for native-
type-vs-validated-string is stated abstractly without naming un-built Wave 3
vocab. Codegen skill cross-reference updated to point at the renamed section.
Conformance fixtures regenerated for all four stacks.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GF9xLEQZaPus5Y6opk398n
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
2 participants
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.
Generalizes the vocabulary-expansion framework so it transfers to ANY future decision: the guiding question is semantic behavior, not surface storage. Subtype test is now behavioral (own native type OR behavior OR attributes → subtype, the extension point); @kind chartered as the one structural-variant-within-a-subtype axis; the 'string formats' set splits (url/uri→field.uri, ip→field.inet, only email/hostname→@stringformat).
Updates ADR-0037, ADR-0036 decision #2, CLAUDE.md, and the agent-context authoring/codegen skills with a mechanical decision procedure an LLM can follow for any concept (illustrated with live vocab only; grounding/conformance/drift green 13/13).
🤖 Generated with Claude Code