Add @haverstack/commons package with canonical type definitions - #166
Merged
Conversation
- @haverstack/commons exports canonical Draft-status commons schemas (note, bookmark, task, contact, article, place, page, photo) as constants plus a defineCommonsTypes(stack, [...]) helper, so apps register commons types exactly as written instead of hand-copying TypeScript out of markdown. - Graduate org.haverstack/photo@1 from Staged to Draft: #63 (file-ref field kind) has landed, so its required image field is now schema-enforced as originally designed. Update docs/commons/README.md's namespace list, type table, and Statuses paragraph accordingly. - Revisit stale "once file-ref fields (#63) land" follow-up notes in the README's embed cross-type convention, note.md, and folder.md now that #63 has shipped. - Update docs/commons/README.md's tooling section and the root README's package table/directory structure to reflect the new package. Closes #146.
file-ref (#63), merge-patch semantics (#69), the first-recorded rule (#65), dangerous-type safe-listing (#66), the strengthened isCompatible relation (#54), and the recoverability model (#59) are all shipped — citing their tracking issues no longer tells a reader anything they can't already get from the doc itself. State each as settled fact instead. Issue references to genuinely open/deferred work (#15, #16, #49, #51, #57/#58) are left as-is.
Self-certified DID identity (#49), reference-implies-access (#51), and the grant/group reshape (#57/#58) are all closed and their outcomes are already reflected in docs/spec/identity.md and docs/spec/access-control.md. State each as settled fact instead of citing the tracking issue: - The DID identity model is described directly rather than pointing at #49; contact.md and message.md no longer treat it as a dependency. - folder.md states plainly that the permission model has no reference-implies-access or inherited mechanism, rather than framing it as an open question tied to #51. - task.md, message.md, and README.md describe assignment/reactions/the group cluster against the grant/group model that already exists (`_group`, type-level grants) instead of citing #57/#58 as a pending dependency. Open work (#15, #16) is left as-is — the docs already frame those as deferred, and that's still accurate.
The repo has no install base to cater to, so prose narrating "this used to be blocked / is no longer necessary" is dead weight once the current state is what matters. State the present design directly: - The Tooling section describes what defineCommonsTypes() does today instead of framing it as relief from a prior requirement. - The Statuses paragraph defines Staged/Proposed generically rather than walking through photo's history to illustrate them (that history still lives in photo.md's own changelog, where it belongs).
Minor follow-up to the previous pass: "already self-certifying" and "already used for entityId" still carried an implicit before/after framing. State the DID identity model as a plain fact instead.
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.
Summary
Introduces
@haverstack/commons, a new package that exports canonical Schema Commons type definitions as constants and provides adefineCommonsTypes()helper. This makes registering commons types a one-liner and prevents schema drift by eliminating hand-copying schemas from documentation.The package exports eight Draft-status commons types (
NOTE,BOOKMARK,TASK,CONTACT,ARTICLE,PLACE,PAGE,PHOTO) asCommonsTypeconstants mirroring theirstack.defineType(...)blocks exactly. ThedefineCommonsTypes(stack, types)helper registers these types on a stack, with idempotent re-registration as the normal path.Also promotes
photofrom Staged to Draft status in the commons documentation, now thatfile-reffields (#63) have landed and the requiredimagefield can be schema-enforced.Spec
No behavior change. The commons types and their schemas are already documented in
docs/commons/; this package makes them available as importable constants rather than requiring manual transcription. ThedefineCommonsTypes()helper is a thin loop overstack.defineType()with no new semantics.Verification
packages/commons/tests/index.test.ts) covering:defineCommonsTypes()registration and idempotencyfile-reffield enforcementtscNotes for reviewers
defineCommonsTypes()is safe to call on every app startup — re-registering already-defined types is the idempotent no-op pathphototype promotion from Staged to Draft is now safe becausefile-reffields are implemented, allowing the requiredimagefield to be schema-enforced rather than convention-onlydocs/commons/README.md; this package's constants are updated to match once proposals landhttps://claude.ai/code/session_0176g68eiBQtrYZxXbNZTd9L