feat(commons): scaffold commons/ with canonical type specs#43
Merged
Conversation
Establishes the in-repo proof of concept for the candy commons discussed in PR #42's review thread. Each shipped example currently re-declares the same `Email`, `Money`, `Hash`, `Token`, `Password`, `Phone` blocks with byte-identical bodies. This directory hosts the canonical version once. Layout: one file per type at `commons/types/<TypeName>.candy`. Each file contains exactly one top-level `spec` block with prose-rich intent + examples (the same shape `policy` already uses). Status — provisional syntax. The `spec` block, the `use spec` line, and the `refines` extension are not yet in `GRAMMAR.md`. A grammar ratification PR will follow; once it lands, the linter will recognise these blocks and projects can adopt them via `use spec Email, Hash, Token` etc. Until then `candy lint` silently ignores `spec` (unknown top-level keyword), so the directory is safe to ship without breaking lint. Six types shipped: Email, Money, Hash, Token, Password, Phone. Money carries one consumer-pinned parameter (`currency`); the rest take their canonical shape unparameterized. Deliberately omitted: `Key` (project-defined identifier per session feedback), `Role` (every project's roles differ), `Id` and `Timestamp` (already language built-ins per `GRAMMAR.md` §type "Built-in named types"). Refs #42 (built-in types discussion).
This was referenced May 7, 2026
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.
Summary
Establishes the in-repo candy commons discussed in PR #42's review
thread. Six canonical type specs that today every example
re-declares with byte-identical bodies, written once.
Layout
```
commons/
README.md
types/
Email.candy — RFC 5322 email; max 320; case-insensitive compare
Money.candy — integer minor units; pinned currency parameter
Hash.candy — one-way hash; constant-time verify; argon2 default
Token.candy — opaque bearer; max 256; never logged
Password.candy — transient plaintext; never persisted
Phone.candy — E.164 normalised at construction
```
One file per type. Each contains exactly one `spec` block with the
`policy`-style prose (`intent:` + meta fields + `examples:`).
Status — provisional syntax
The `spec` block, the `use spec` line, and the `refines` extension
are not yet in `GRAMMAR.md`. A grammar ratification PR follows
separately; once it lands the linter will recognise these blocks and
projects can adopt them via `use spec Email, Hash, Token` (and pin
parameters via `use spec Money(currency: USD)`).
Until ratification, `candy lint` silently ignores `spec` blocks
(unknown top-level keyword falls through the parser's recovery
path). `candy lint commons/` exits 0; nothing about this PR breaks
lint or CI.
Deliberate omissions
type is project-defined. Projects that prefer `IdempotencyKey`
shouldn't have to fight a commons spec named `Key`.
guest/host/admin vs customer/admin). No commons candidate.
(`GRAMMAR.md` §type "Built-in named types"). They never needed a
spec.
Future structure
When the grammar ratification PR lands, follow-ups for
`commons/policies/`, `commons/events/`, `commons/externals/` open up.
Out of scope here.
Test plan
unknown keyword).
`spec` blocks and `candy lint commons/` reports zero violations
in this corpus.
as the proof-point for the resolution mechanic. Separate PR.
Refs