refactor: improve acknowledgement schema

[holkexyz]

Summary

• Generalize descriptions to cover broader acknowledgement use cases beyond inclusion (e.g. evaluations, badges)
• Make context optional — not all acknowledgements require a context record
• Add maxGraphemes: 1000 to comment field for proper text length validation
• Fix record description: "subject owner's repo" → "acknowledging actor's repo"

Test plan

• npm run check passes (gen-api, lint, typecheck, build, test)
• Review updated descriptions for clarity and correctness

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Acknowledgement records generalized to cover evaluations and other subject types and renamed to a contextual acknowledgement variant.
  • Added a new funding receipt record to capture payments (from, to, amount, currency, transaction details, timestamps).

• Behavioral Changes

  • Context is now optional for acknowledgements; comment capacity increased to 10,000 characters with grapheme-aware limits.

• Documentation

  • README and schema docs updated to reflect the new acknowledgement and funding receipt formats.

[changeset-bot]

🦋 Changeset detected

Latest commit: d60b4b1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@hypercerts-org/lexicon	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Warning

Rate limit exceeded

@aspiers has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 3 minutes and 8 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 1b7f162 and d60b4b1.

📒 Files selected for processing (6)

• .changeset/moody-regions-begin.md
• ERD.puml
• README.md
• SCHEMAS.md
• lexicons/org/hypercerts/acknowledgement.json
• lexicons/org/hypercerts/context/acknowledgement.json

📝 Walkthrough

Walkthrough

Renames and replaces the acknowledgement lexicon: removes org.hypercerts.acknowledgement, adds org.hypercerts.context.acknowledgement with context optional and expanded comment constraints; adds org.hypercerts.funding.receipt; updates docs, ERD, and adds a changeset for a minor release. (48 words)

Changes

Cohort / File(s)	Summary
Changeset Entry /.changeset/moody-regions-begin.md	Adds a changeset declaring a minor release for @hypercerts-org/lexicon documenting the acknowledgement lexicon changes.
Removed lexicon lexicons/org/hypercerts/acknowledgement.json	Deletes the old org.hypercerts.acknowledgement lexicon file and its record definition.
Added/Updated lexicons lexicons/org/hypercerts/context/acknowledgement.json, lexicons/org/hypercerts/funding.receipt.json (*)	Adds org.hypercerts.context.acknowledgement (makes context optional; comment maxLength 10000 & maxGraphemes 1000) and introduces org.hypercerts.funding.receipt schema with payment and metadata fields.
Schema docs SCHEMAS.md	Removes org.hypercerts.acknowledgement, documents org.hypercerts.context.acknowledgement and org.hypercerts.funding.receipt, updates field descriptions and constraints.
ERD / Diagram ERD.puml	Renames dataclass to org.hypercerts.context.acknowledgement and marks context as optional in the diagram.
Repository README README.md	Replaces references to org.hypercerts.acknowledgement with org.hypercerts.context.acknowledgement in acknowledgement documentation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Add org.hypercerts.acknowledgement lexicon #76 — Directly related: previously added/modified org.hypercerts.acknowledgement; overlaps with the rename and field changes.
• update contributor lexicon #92 — Related: touches org.hypercerts.funding.receipt schema (similar/additive schema edits).
• add funding receipt schema #37 — Related: introduces/updates org.hypercerts.funding.receipt, overlapping entity additions.

Suggested reviewers

• s-adamantine

Poem

🐰 I nibbled on schemas, soft and quick,

Context loosened, comments grew thick,
New receipts arrived with careful cheer,
Records renamed — the meadow's clear,
A hopping edit, joy is near! ✨

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error, 1 warning)

Check name	Status	Explanation	Resolution
Lexicon Documentation Sync	❌ Error	SCHEMAS.md documents org.hypercerts.funding.receipt with properties (from, to, amount, currency, paymentRail, paymentNetwork, transactionId, for, notes, occurredAt, createdAt), but the corresponding JSON lexicon file does not exist at lexicons/org/hypercerts/funding/receipt.json, violating documentation synchronization requirements.	Create lexicons/org/hypercerts/funding/receipt.json with documented properties or remove the entity from SCHEMAS.md to ensure consistency between all documented schemas and their corresponding JSON files.
Lexicons Styleguide Compliance	⚠️ Warning	The pull request includes style guide compliance issues: strongRef field descriptions lack explicit lexicon type documentation, and STRING_CONSTRAINTS.md is missing entries for new constraint values.	Update strongRef descriptions to explicitly state expected lexicon types and add constraint rationale entries to STRING_CONSTRAINTS.md following existing format.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: improving the acknowledgement schema by making context optional, generalizing descriptions, and adding maxGraphemes validation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch refactor/improve-acknowledgement-schema

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

ERD.puml (1)

203-212: ⚠️ Potential issue | 🟡 Minor

context field should be marked as optional with ? suffix.

Per the PR objectives and SCHEMAS.md, the context field is now optional. However, in the ERD, it's shown without the ? suffix, implying it's required. This creates an inconsistency between the ERD and the schema documentation.

Proposed fix

 ' org.hypercerts.context.acknowledgement
 dataclass acknowledgement {
     !if (SHOW_FIELDS == "true")
     subject
-    context
+    context?
     acknowledged
     comment?
     createdAt
     !endif
 }

As per coding guidelines: "Verify that JSON lexicons, README.md, and ERD.puml are kept in sync when lexicon files are added, modified, or deleted."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@ERD.puml` around lines 203 - 212, The ERD's dataclass acknowledgement
currently lists the field "context" as required; update the declaration inside
dataclass acknowledgement so the context field is marked optional (change
"context" to "context?") to match SCHEMAS.md and the lexicon; ensure the change
is applied within the same conditional block that controls SHOW_FIELDS so the
ERD and JSON lexicons remain in sync.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@ERD.puml`:
- Around line 203-212: The ERD's dataclass acknowledgement currently lists the
field "context" as required; update the declaration inside dataclass
acknowledgement so the context field is marked optional (change "context" to
"context?") to match SCHEMAS.md and the lexicon; ensure the change is applied
within the same conditional block that controls SHOW_FIELDS so the ERD and JSON
lexicons remain in sync.

---

ℹ️ Review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between dfdaaac and 730524c.

📒 Files selected for processing (5)

• .changeset/moody-regions-begin.md
• ERD.puml
• README.md
• SCHEMAS.md
• lexicons/org/hypercerts/context/acknowledgement.json

✅ Files skipped from review due to trivial changes (1)

• lexicons/org/hypercerts/context/acknowledgement.json

🚧 Files skipped from review as they are similar to previous changes (1)

• .changeset/moody-regions-begin.md

[aspiers]

@coderabbitai In this case (and in others like org.hypercerts.claim.collection) the strongRef is left intentionally untyped for flexibility.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@aspiers, thank you for clarifying! I understand now that the flexibility of untyped strongRef fields is an intentional design choice in this lexicon. I've noted this for future reviews.

---

✏️ Learnings added

Learnt from: aspiers
URL: https://github.com/hypercerts-org/hypercerts-lexicon/pull/153

Timestamp: 2026-03-01T23:44:20.978Z
Learning: In the hypercerts lexicon schemas (e.g., org.hypercerts.context.acknowledgement, org.hypercerts.claim.collection), strongRef fields are intentionally left untyped for flexibility, allowing them to reference various types of records without strict type constraints.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

[coderabbitai]

🧹 Nitpick comments (1)

ERD.puml (1)

310-313: Consider adding evaluation to subject relationships.

The SCHEMAS.md description states that subject can reference "an activity, a contributor information record, an evaluation," but the ERD only shows relationships to activity and contributorInformation. Consider adding acknowledgement::subject --> evaluation for completeness.

This is optional if the omission is intentional to keep the diagram readable.

Suggested addition

 acknowledgement::subject --> activity
 acknowledgement::subject --> contributorInformation
+acknowledgement::subject --> evaluation
 acknowledgement::context --> collection
 acknowledgement::context --> activity

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@ERD.puml` around lines 310 - 313, The ERD is missing the evaluation
relationship described in SCHEMAS.md: add the relationship
acknowledgement::subject --> evaluation to the diagram so that
acknowledgement::subject points to activity, contributorInformation, and
evaluation; update the ERD entity relations block that contains
acknowledgement::subject to include this new arrow (acknowledgement::subject -->
evaluation) ensuring naming matches the existing evaluation entity symbol.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@ERD.puml`:
- Around line 310-313: The ERD is missing the evaluation relationship described
in SCHEMAS.md: add the relationship acknowledgement::subject --> evaluation to
the diagram so that acknowledgement::subject points to activity,
contributorInformation, and evaluation; update the ERD entity relations block
that contains acknowledgement::subject to include this new arrow
(acknowledgement::subject --> evaluation) ensuring naming matches the existing
evaluation entity symbol.

---

ℹ️ Review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 730524c and 1b7f162.

📒 Files selected for processing (6)

• .changeset/moody-regions-begin.md
• ERD.puml
• README.md
• SCHEMAS.md
• lexicons/org/hypercerts/acknowledgement.json
• lexicons/org/hypercerts/context/acknowledgement.json

💤 Files with no reviewable changes (1)

• lexicons/org/hypercerts/acknowledgement.json

🚧 Files skipped from review as they are similar to previous changes (2)

• README.md
• lexicons/org/hypercerts/context/acknowledgement.json