docs: fix mutability section in core data model#67
Merged
Conversation
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughUpdated documentation: added a "Last updated" timestamp, changed mutability to state records are currently immutable after creation, revised linking language to emphasize detectability rather than blanket strong-reference claims, introduced structured workScope usage in examples, and added a new callout CSS variant. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@pages/core-concepts/hypercerts-core-data-model.md`:
- Around line 8-9: Update the hardcoded future dates in the page metadata:
replace "Last updated: March 5, 2026" (and the other occurrence around line 93)
with a non-future date (e.g., "March 4, 2026") or remove the hardcoded date
fields entirely to avoid future churn; ensure you edit the exact strings in the
markdown header/body where "Last updated: March 5, 2026" appears so both
occurrences are consistent.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: b71c53c6-038e-4068-84c5-6e593faf1bd3
📒 Files selected for processing (1)
pages/core-concepts/hypercerts-core-data-model.md
There was a problem hiding this comment.
♻️ Duplicate comments (2)
pages/core-concepts/hypercerts-core-data-model.md (2)
93-93:⚠️ Potential issue | 🟡 MinorFuture-dated timestamp should use current date.
The timestamp "(As of March 5, 2026)" is future-dated. Update to March 4, 2026 to match the PR creation date.
📅 Proposed fix
-Activity claims and their linked records are currently immutable once created. Record versioning and edit history are not yet supported — this is an active area of design work. *(As of March 5, 2026)* +Activity claims and their linked records are currently immutable once created. Record versioning and edit history are not yet supported — this is an active area of design work. *(As of March 4, 2026)*🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/core-concepts/hypercerts-core-data-model.md` at line 93, Update the future-dated timestamp string "(As of March 5, 2026)" to "(As of March 4, 2026)"; locate the timestamp text in the hypercerts core data model document (the literal string "(As of March 5, 2026)") and replace it with the corrected date to match the PR creation date.
8-9:⚠️ Potential issue | 🟡 MinorFuture-dated timestamp should use current date.
The "Last updated" date is March 5, 2026, but this PR was created on March 4, 2026. Update to the current date or remove the hardcoded date to avoid inaccuracy.
📅 Proposed fix
-*Last updated: March 5, 2026* +*Last updated: March 4, 2026*🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/core-concepts/hypercerts-core-data-model.md` around lines 8 - 9, Update the hardcoded "Last updated: March 5, 2026" line in the document: either set it to the current date (e.g., "Last updated: March 4, 2026") or remove the static "Last updated" line entirely; alternatively replace it with a dynamic mechanism if your build system supports it so the timestamp is always generated at build time (edit the line containing "*Last updated: March 5, 2026*").
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@pages/core-concepts/hypercerts-core-data-model.md`:
- Line 93: Update the future-dated timestamp string "(As of March 5, 2026)" to
"(As of March 4, 2026)"; locate the timestamp text in the hypercerts core data
model document (the literal string "(As of March 5, 2026)") and replace it with
the corrected date to match the PR creation date.
- Around line 8-9: Update the hardcoded "Last updated: March 5, 2026" line in
the document: either set it to the current date (e.g., "Last updated: March 4,
2026") or remove the static "Last updated" line entirely; alternatively replace
it with a dynamic mechanism if your build system supports it so the timestamp is
always generated at build time (edit the line containing "*Last updated: March
5, 2026*").
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 8074d5b5-18f3-49b0-9b82-931321a55661
📒 Files selected for processing (1)
pages/core-concepts/hypercerts-core-data-model.md
…g-your-first-hypercert - Rewrite intro to link to activity claim lexicon - Clean up dimension table with human-readable examples - Rewrite collections section (flexible grouping, not just projects) - Fix mutability section (immutable for now, versioning and locking planned) - Remove unimplemented onchain snapshot paragraph - Simplify strong references to glossary link - Replace ERD image with latest SVG from lexicon repo, note tokenization not yet implemented - Add last updated date - Add field reference (contributors, work scopes, time, locations) to creating-your-first-hypercert - Fix workScope from allOf to workScopeString per current lexicon
s-adamantine
force-pushed
the
fix/data-model-mutability
branch
from
4c5d306 to
a8a42e4
Compare
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (1)
pages/core-concepts/hypercerts-core-data-model.md (1)
8-8:⚠️ Potential issue | 🟡 MinorFuture-dated “Last updated” value is still inaccurate.
Line 8 says “March 5, 2026,” which is in the future relative to this PR date. Please use a non-future date (e.g., March 4, 2026) or remove hardcoded dating.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/core-concepts/hypercerts-core-data-model.md` at line 8, Update the hardcoded future "Last updated" metadata by editing the markdown line containing "*Last updated: March 5, 2026*" in pages/core-concepts/hypercerts-core-data-model.md: either change the date to a non-future date (e.g., "March 4, 2026") or remove the hardcoded "Last updated" line entirely so it doesn't show a future date.
🧹 Nitpick comments (1)
pages/core-concepts/hypercerts-core-data-model.md (1)
70-70: Wording at Line 70 conflicts with current immutability claim.Line 70 says referenced records can be modified, while Line 90 states records are currently immutable. Consider rephrasing to avoid implying current in-place edits.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/core-concepts/hypercerts-core-data-model.md` at line 70, The sentence "Records reference each other using [strong references] — if a referenced record is modified after the reference was created, the change is detectable." conflicts with the later immutability claim; update the wording for the "Records reference each other using [strong references]" sentence to avoid implying in-place edits (for example, state that references detect changes to the referenced record's state/history or new versions rather than saying "modified"), so it aligns with the immutability statement on Line 90 and preserves the concept of detectability of subsequent changes or new versions.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@pages/core-concepts/hypercerts-core-data-model.md`:
- Line 44: Replace the inconsistent spelling "onchain" with "on-chain" in the
document where the token entity is described (the sentence mentioning
tokenization/anchoring a hypercert onchain); locate the occurrence of the word
"onchain" near the "token" entity reference and update it to "on-chain" for
consistency.
In `@pages/getting-started/creating-your-first-hypercert.md`:
- Line 31: The inline workScope example currently shows an untyped object `{
scope: "Documentation" }`; update it to the typed inline form by adding the
`$type` discriminator so it matches other examples (e.g., use the `workScope`
object with `$type` and `scope` fields) to avoid copy/paste errors and keep
examples consistent with those at workScope and $type usage elsewhere in the
document.
In `@styles/globals.css`:
- Around line 1304-1307: The new CSS variant .callout--note is unreachable
because the Markdoc validator in markdoc/tags/callout.markdoc.js currently
rejects type="note"; either add "note" to the allowed matches array in that
Markdoc validator (so Markdoc will generate elements with data/type or class for
note) or remove the .callout--note rule from styles/globals.css; locate the
validator file (markdoc/tags/callout.markdoc.js) and update its matches list to
include "note" (or delete the CSS selector) and ensure the template/rendering
emits the corresponding class or attribute used by .callout--note.
---
Duplicate comments:
In `@pages/core-concepts/hypercerts-core-data-model.md`:
- Line 8: Update the hardcoded future "Last updated" metadata by editing the
markdown line containing "*Last updated: March 5, 2026*" in
pages/core-concepts/hypercerts-core-data-model.md: either change the date to a
non-future date (e.g., "March 4, 2026") or remove the hardcoded "Last updated"
line entirely so it doesn't show a future date.
---
Nitpick comments:
In `@pages/core-concepts/hypercerts-core-data-model.md`:
- Line 70: The sentence "Records reference each other using [strong references]
— if a referenced record is modified after the reference was created, the change
is detectable." conflicts with the later immutability claim; update the wording
for the "Records reference each other using [strong references]" sentence to
avoid implying in-place edits (for example, state that references detect changes
to the referenced record's state/history or new versions rather than saying
"modified"), so it aligns with the immutability statement on Line 90 and
preserves the concept of detectability of subsequent changes or new versions.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 9fe1b3be-f204-4fcf-b4d6-4fa704520882
⛔ Files ignored due to path filters (1)
public/images/hypercert-erd.svgis excluded by!**/*.svg
📒 Files selected for processing (3)
pages/core-concepts/hypercerts-core-data-model.mdpages/getting-started/creating-your-first-hypercert.mdstyles/globals.css
| {% figure src="/images/hypercert-erd.png" alt="Hypercert record relationships" /%} | ||
| {% figure src="/images/hypercert-erd.svg" alt="Hypercert record relationships" /%} | ||
|
|
||
| The diagram includes a **token** entity — tokenization (anchoring a hypercert onchain) is not yet implemented. |
There was a problem hiding this comment.
Use “on-chain” spelling for consistency.
Line 44 should use “on-chain” instead of “onchain.”
🧰 Tools
🪛 LanguageTool
[grammar] ~44-~44: Ensure spelling is correct
Context: ...y — tokenization (anchoring a hypercert onchain) is not yet implemented. | Record type...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@pages/core-concepts/hypercerts-core-data-model.md` at line 44, Replace the
inconsistent spelling "onchain" with "on-chain" in the document where the token
entity is described (the sentence mentioning tokenization/anchoring a hypercert
onchain); locate the occurrence of the word "onchain" near the "token" entity
reference and update it to "on-chain" for consistency.
| The activity claim is the core record — it describes what work was done, when, and in what scope. Here's how each field maps to the [activity lexicon](/lexicons/hypercerts-lexicons/activity-claim): | ||
|
|
||
| - **Contributors** can be identified inline with a DID or by referencing a [`contributorInformation`](/lexicons/hypercerts-lexicons/activity-claim) record that includes a display name and image. Each contributor can also have a weight and role. | ||
| - **Work scopes** can be a simple free-form string (`{ scope: "Documentation" }`) or a structured [CEL expression](/core-concepts/work-scopes) for machine-evaluable queries across the network. |
There was a problem hiding this comment.
Inline workScope example is missing $type.
Line 31’s example ({ scope: "Documentation" }) is inconsistent with the actual examples (Lines 43 and 69) and may cause copy/paste errors. Show the typed inline form here as well.
Suggested patch
-- **Work scopes** can be a simple free-form string (`{ scope: "Documentation" }`) or a structured [CEL expression](/core-concepts/work-scopes) for machine-evaluable queries across the network.
+- **Work scopes** can be a simple inline string object (`{ $type: "org.hypercerts.claim.activity#workScopeString", scope: "Documentation" }`) or a structured [CEL expression](/core-concepts/work-scopes) for machine-evaluable queries across the network.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - **Work scopes** can be a simple free-form string (`{ scope: "Documentation" }`) or a structured [CEL expression](/core-concepts/work-scopes) for machine-evaluable queries across the network. | |
| - **Work scopes** can be a simple inline string object (`{ $type: "org.hypercerts.claim.activity#workScopeString", scope: "Documentation" }`) or a structured [CEL expression](/core-concepts/work-scopes) for machine-evaluable queries across the network. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@pages/getting-started/creating-your-first-hypercert.md` at line 31, The
inline workScope example currently shows an untyped object `{ scope:
"Documentation" }`; update it to the typed inline form by adding the `$type`
discriminator so it matches other examples (e.g., use the `workScope` object
with `$type` and `scope` fields) to avoid copy/paste errors and keep examples
consistent with those at workScope and $type usage elsewhere in the document.
Comment on lines
+1304
to
+1307
| .callout--note { | ||
| border-left: 4px solid var(--color-info); | ||
| background: var(--color-info-bg); | ||
| } |
There was a problem hiding this comment.
callout--note is unreachable with current Markdoc validation.
Line 1304 adds a new variant, but markdoc/tags/callout.markdoc.js still rejects type="note" as a critical validation error. Either allow "note" in the Markdoc matches list or remove this variant to avoid dead CSS.
Suggested patch (Markdoc validator)
--- a/markdoc/tags/callout.markdoc.js
+++ b/markdoc/tags/callout.markdoc.js
@@
- matches: ['info', 'warning', 'danger', 'success'],
+ matches: ['info', 'note', 'warning', 'danger', 'success'],🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@styles/globals.css` around lines 1304 - 1307, The new CSS variant
.callout--note is unreachable because the Markdoc validator in
markdoc/tags/callout.markdoc.js currently rejects type="note"; either add "note"
to the allowed matches array in that Markdoc validator (so Markdoc will generate
elements with data/type or class for note) or remove the .callout--note rule
from styles/globals.css; locate the validator file
(markdoc/tags/callout.markdoc.js) and update its matches list to include "note"
(or delete the CSS selector) and ensure the template/rendering emits the
corresponding class or attribute used by .callout--note.
This was referenced Mar 4, 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.
Fixes HYPER-149
Summary
allOftoworkScopeStringcallout--noteCSS style