feat: add CEL expression support for structured work scopes

[holkexyz]

Summary

Implements the two-layer work scope model from the CEL for Hypercerts design document, enabling machine-evaluable, composable work scope definitions on activity records.

• New: org.hypercerts.ontology.celExpression — CEL expression object type with expression, usedTags (strongRef array to workScopeTag records), version (knownValues: v1), and createdAt
• New: org.hypercerts.ontology.workScopeTag — reusable scope atoms with lifecycle fields (status, supersededBy), interop (sameAs), kind with knownValues, and underscore-separated key convention for CEL compatibility
• Updated: activity.workScope union now includes [celExpression, strongRef, workScopeString] with CEL as the primary variant
• Updated: ERD with new entities and relationships
• Updated: README example to show CEL expression usage with strongRef usedTags

Key design decisions

Aspect	Decision	Rationale
Namespace	org.hypercerts.ontology.*	Distinguishes ontology/taxonomy schemas from claim data
usedTags field	strongRef[] (not plain strings)	Provides referential integrity to workScopeTag records while still enabling fast AT-URI indexing by appviews
version field	Required, knownValues: ["v1"]	Open enum — new context schema versions can be added non-breakingly; context schema formalization deferred until evaluator is built
CEL expression type	object (not record)	Can be embedded inline in union types without requiring a separate collection

Architecture

activity.workScope --> celExpression (object, inline)
                         usedTags[] --> workScopeTag (strongRef)
                   --> strongRef (future extensibility)
                   --> workScopeString (simple/legacy fallback)

workScopeTag (record, own collection)
  parent --> workScopeTag (hierarchy)
  supersededBy --> workScopeTag (deprecation)
  sameAs[] --> external ontologies (Wikidata, ENVO, SDGs)

Test plan

• npm run check passes (gen-api, lint, typecheck, build, 7/7 tests)
• node scripts/check-lexicon-style.js — 0 errors on new files
• SCHEMAS.md regenerated with new sections
• Visual review of ERD rendering

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Added CEL expression support for structured, machine-evaluable work scopes in claims
  • Enhanced work scope tag definitions with hierarchical relationships, metadata fields, and status tracking (aliases, parent references, deprecation markers)

• Documentation

  • Updated schema documentation and examples to reflect CEL-based work scope definitions
  • Improved work scope field descriptions and constraints

[changeset-bot]

🦋 Changeset detected

Latest commit: 7418834

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]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR introduces CEL (Common Expression Language) support for structured work scopes by adding two new lexicon definitions, removing the legacy helper-based work scope tag, updating the activity lexicon to reference the new CEL type, and revising documentation and schema generation logic accordingly.

Changes

Cohort / File(s)	Summary
New CEL Work Scope Lexicons lexicons/org/hypercerts/workscope/cel.json, lexicons/org/hypercerts/workscope/tag.json	Added new lexicon definitions: org.hypercerts.workscope.cel with fields expression, usedTags, version, createdAt; and enhanced org.hypercerts.workscope.tag with structured metadata (key, name, category, description, parent, status, supersededBy, aliases, sameAs, referenceDocument, createdAt).
Removed Legacy Work Scope Definition lexicons/org/hypercerts/helper/workScopeTag.json	Deleted the previous helper-based work scope tag lexicon definition (65 lines removed).
Activity Lexicon Update lexicons/org/hypercerts/claim/activity.json	Updated workScope field union from com.atproto.repo.strongRef to org.hypercerts.workscope.cel and revised description to reflect CEL expression semantics instead of strongRef.
Data Model Definitions ERD.puml	Added public data models org.hypercerts.ontology.celExpression and org.hypercerts.ontology.workScopeTag; updated org.hypercerts.claim.rights signature; established cross-entity relationships (activity → celExpression, celExpression → workScopeTag, workScopeTag hierarchy/deprecation links).
Documentation & Examples README.md, SCHEMAS.md	Updated work scope examples and documentation to demonstrate CEL expression structure; revised schema descriptions to reference new CEL-based definitions and removed references to legacy helper tags.
Build Script & Metadata scripts/generate-schemas.js, .changeset/add-cel-work-scope-expressions.md	Refined schema generation logic to handle properties conditionally based on entity type; added changeset entry documenting minor version bump for new CEL expression support.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• Issue #150: Directly implements the CEL work-scope proposal by introducing org.hypercerts.workscope.cel and enhanced org.hypercerts.workscope.tag lexicons and updating the activity lexicon to use CEL-based definitions.

Possibly related PRs

• PR #107: Both modify org.hypercerts.claim.activity.workScope and introduce/refactor work-scope tag types; this PR replaces the helper tag with a CEL-based model while the other introduced a boolean-logic AST variant.
• PR #132: Both update the same activity.workScope union field in the activity lexicon, with this PR replacing the strongRef variant with org.hypercerts.workscope.cel.
• PR #31: Both modify the same activity.workScope lexicon schema file, introducing structural changes to work-scope definitions.

Poem

🐰 CEL expressions hop into the fold,
Structured scopes, a story newly told,
Tags dance with hierarchy so fine,
Legacy helpers fade—the future's design! ✨

---

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	JSON lexicons, README.md, and ERD.puml are not properly synchronized. README documents unsupported workScope union option; ERD.puml uses incorrect namespace comments and mismatched workScopeTag fields.	Update README.md to remove strongRef workScope example. Correct ERD.puml namespace comments and workScopeTag field names to match actual schema.
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ 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 clearly and accurately summarizes the main change: adding CEL expression support for structured work scopes, which is the central feature across all modified files.
Lexicons Styleguide Compliance	✅ Passed	Lexicon files comply with ATProto Lexicon Style Guide with proper naming conventions, descriptions, and documented deviations.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/cel-work-scope-expressions

---

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]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@lexicons/org/hypercerts/helper/celExpression.json`:
- Around line 1-38: The lexicon org.hypercerts.helper.celExpression uses main
with type: "object" which deviates from the repo convention (most top-level
lexicons use type: "record"); either convert main to type: "record" with key:
"tid" (preserving properties expression, labels, version, createdAt) to match
the generator, or keep type: "object" but add a top-level description field in
the JSON that documents the deviation and rationale (mentioning it's intended
for inline-only embedding and referencing the CEL use-case), and note that the
SCHEMAS.md generator must be updated to handle object-type mains so properties
are rendered correctly; modify either the main definition or the description in
org.hypercerts.helper.celExpression accordingly.

In `@lexicons/org/hypercerts/helper/workScopeTag.json`:
- Around line 23-28: You renamed the optional field workScopeTag.kind to type
which will silently break existing clients; instead preserve the original schema
and introduce a backwards-incompatible new schema (e.g., workScopeTagV2) that
defines "type" (and mark "kind" deprecated in the old schema if desired), update
any AppViews/clients to consume workScopeTagV2 before switching, and coordinate
a migration/communication plan; locate the definitions by the schema name
workScopeTag and the fields kind/type to add the new workScopeTagV2 schema and
keep the original schema unchanged until consumers are updated.

In `@SCHEMAS.md`:
- Around line 296-297: The table in SCHEMAS.md incorrectly lists `aliases` and
`sameAs` as Type `string` while their JSON schema defines them as arrays; update
the Type column entries for the `aliases` and `sameAs` rows to reflect an array
of strings/URIs (e.g., "string[]" or "array of string/URI") so it matches the
schema's `type: "array"` and keep the existing `maxLength` comment unchanged;
ensure the row labels `aliases` and `sameAs` are the ones edited to maintain
consistency with the schema.
- Around line 271-277: The org.hypercerts.helper.celExpression section in
SCHEMAS.md is wrong: change/remove the incorrect "**Key:** `tid`" (it should not
declare a record key because celExpression.json defines main as type: "object")
and add a properties table documenting the four required fields from
celExpression.json: expression, labels, version, createdAt; update the section
header/body for org.hypercerts.helper.celExpression to reflect that main is an
object (not a record) and list each property name, type, description, and
required status per the celExpression.json schema so the generated docs match
the source.

---

ℹ️ 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 2bb200c and 097cb84.

📒 Files selected for processing (7)

• .changeset/add-cel-work-scope-expressions.md
• ERD.puml
• README.md
• SCHEMAS.md
• lexicons/org/hypercerts/claim/activity.json
• lexicons/org/hypercerts/helper/celExpression.json
• lexicons/org/hypercerts/helper/workScopeTag.json

[holkexyz]

Addressed all CodeRabbitAI comments in 082a242:

1. celExpression type:object deviation — Added rationale directly in the lexicon description explaining why it's intentionally type: "object" (for inline embedding in unions without strongRef indirection).

2. SCHEMAS.md incomplete/wrong for celExpression — Fixed the generator to handle type: "object" main defs: no Key: line is emitted, and properties are read directly from main instead of main.record. The celExpression section now correctly shows all 4 properties.

3. kind → type rename — Not a concern. The package is pre-release (0.x) with no production consumers of workScopeTag.kind. The field was only introduced recently and has not been used in any deployed AppView or client.

4. aliases and sameAs shown as string instead of array — Fixed getTypeString() to render array types as type[] (e.g., string[], ref[]).

[coderabbitai]

♻️ Duplicate comments (1)

SCHEMAS.md (1)

338-338: ⚠️ Potential issue | 🔴 Critical

Stale field name — type here should be kind after the field revert, causing the CI failure.

This auto-generated file still reflects the intermediate state where the field was renamed type. The source JSON (workScopeTag.json) reverted it back to kind, but SCHEMAS.md was not regenerated. The CI git diff --exit-code check catches this exactly.

Regenerating SCHEMAS.md from the current lexicons will fix this line and unblock CI.

🤖 Prompt for AI Agents

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

In `@SCHEMAS.md` at line 338, SCHEMAS.md contains a stale field name `type` for
the work scope tag; regenerate the schema docs from the current lexicons so the
`workScopeTag` entry uses `kind` (matching workScopeTag.json) rather than `type`
to fix the CI git-diff failure; run the doc generation script/process you use
for SCHEMAS.md, verify the table row for the workScopeTag (the line showing
"`type` | `string` | ... Known values") is updated to "`kind`", and commit the
regenerated SCHEMAS.md.

🧹 Nitpick comments (1)

lexicons/org/hypercerts/helper/workScopeTag.json (1)

46-50: Consider documenting the supersededBy/status coupling in more detail.

supersededBy is only meaningful when status is "deprecated", but ATProto doesn't support conditional field validation — this guidance lives only in the description. The description is clear, so this is acceptable, but consider also noting in the status field description that setting status: "deprecated" without a supersededBy reference should be avoided (or calling it out via a knownValues-style annotation).

🤖 Prompt for AI Agents

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

In `@lexicons/org/hypercerts/helper/workScopeTag.json` around lines 46 - 50,
Update the schema documentation to explicitly describe the coupling between
status and supersededBy: in the lexicon org.hypercerts.helper.workScopeTag,
augment the description of the status field to state that when status =
"deprecated" a supersededBy ref to another workScopeTag SHOULD be provided (and
that leaving deprecated without supersededBy is discouraged), and optionally add
a note/annotation (e.g., knownValues-style guidance or a "recommendedUsage"
sentence) next to the status and supersededBy entries to make this constraint
obvious to consumers; ensure you reference the status field and the supersededBy
property by name so readers can find the coupling easily.

🤖 Prompt for all review comments with AI agents

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

Duplicate comments:
In `@SCHEMAS.md`:
- Line 338: SCHEMAS.md contains a stale field name `type` for the work scope
tag; regenerate the schema docs from the current lexicons so the `workScopeTag`
entry uses `kind` (matching workScopeTag.json) rather than `type` to fix the CI
git-diff failure; run the doc generation script/process you use for SCHEMAS.md,
verify the table row for the workScopeTag (the line showing "`type` | `string` |
... Known values") is updated to "`kind`", and commit the regenerated
SCHEMAS.md.

---

Nitpick comments:
In `@lexicons/org/hypercerts/helper/workScopeTag.json`:
- Around line 46-50: Update the schema documentation to explicitly describe the
coupling between status and supersededBy: in the lexicon
org.hypercerts.helper.workScopeTag, augment the description of the status field
to state that when status = "deprecated" a supersededBy ref to another
workScopeTag SHOULD be provided (and that leaving deprecated without
supersededBy is discouraged), and optionally add a note/annotation (e.g.,
knownValues-style guidance or a "recommendedUsage" sentence) next to the status
and supersededBy entries to make this constraint obvious to consumers; ensure
you reference the status field and the supersededBy property by name so readers
can find the coupling easily.

---

ℹ️ 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 097cb84 and ebbc44a.

📒 Files selected for processing (5)

• ERD.puml
• SCHEMAS.md
• lexicons/org/hypercerts/helper/celExpression.json
• lexicons/org/hypercerts/helper/workScopeTag.json
• scripts/generate-schemas.js

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

• ERD.puml
• lexicons/org/hypercerts/helper/celExpression.json

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@ERD.puml`:
- Around line 179-203: The workScopeTag dataclass in ERD.puml is stale and uses
old namespace and field names; update the dataclass named workScopeTag to match
the current lexicon org.hypercerts.workscope.* by replacing deprecated fields
(label → name, kind → category, externalReference → referenceDocument) and
remove or update the outdated namespace comment (org.hypercerts.ontology.*) so
all fields and the entity namespace align with the lexicons in
lexicons/**/*.json; ensure optional fields (parent?, status?, supersededBy?,
aliases[]?, sameAs[]?) remain correct per the lexicon and adjust SHOW_FIELDS
block accordingly.

In `@README.md`:
- Around line 86-89: Replace the placeholder type string "...#workScopeString"
with a concrete NSID that matches the project's schema (e.g., set workScope: {
$type: "org.hypercerts.workScope#workScopeString", scope: "Environmental
conservation" }); update the README example where workScope appears and ensure
the workScope schema name and property "scope" align with the actual JSON schema
for workScope and that startDate remains a valid ISO timestamp; verify the
substituted NSID exactly matches the schema's $type value used in the codebase
(search for workScopeString, workScope, and startDate symbols).

---

ℹ️ 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 3a3f6f7 and 94d6937.

📒 Files selected for processing (10)

• .changeset/add-cel-work-scope-expressions.md
• .prettierignore
• ERD.puml
• README.md
• SCHEMAS.md
• lexicons/org/hypercerts/claim/activity.json
• lexicons/org/hypercerts/helper/workScopeTag.json
• lexicons/org/hypercerts/workscope/cel.json
• lexicons/org/hypercerts/workscope/tag.json
• scripts/generate-schemas.js

💤 Files with no reviewable changes (1)

• lexicons/org/hypercerts/helper/workScopeTag.json

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

• .changeset/add-cel-work-scope-expressions.md

[coderabbitai]

♻️ Duplicate comments (2)

README.md (1)

86-88: ⚠️ Potential issue | 🟡 Minor

Use a concrete NSID for the workScopeString example.

Line 88 still uses the placeholder "...#workScopeString" which is not actionable and can mislead copy/paste usage. Replace with the concrete NSID.

📝 Suggested fix

   // OR a strongRef to a single work scope tag:
   // workScope: { uri: "at://did:plc:alice/org.hypercerts.workscope.tag/abc123", cid: "..." },
-  // OR a simple string: workScope: { $type: "...#workScopeString", scope: "Environmental conservation" },
+  // OR a simple string:
+  // workScope: { $type: "org.hypercerts.claim.activity#workScopeString", scope: "Environmental conservation" },

As per coding guidelines: "When README.md is modified, verify that ... all documented properties match actual JSON schema definitions."

🤖 Prompt for AI Agents

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

In `@README.md` around lines 86 - 88, Replace the placeholder NSID in the
workScope example so it matches the actual schema: change the $type value in the
workScope example (workScope: { $type: "...#workScopeString", scope:
"Environmental conservation" }) to a concrete NSID used by the project (e.g.,
"org.hypercerts.workscope#workScopeString" or the exact NSID defined in your
JSON schema) so the README's workScopeString example is actionable and
copy/paste-ready.

ERD.puml (1)

194-219: ⚠️ Potential issue | 🟠 Major

ERD namespace comments and workScopeTag fields are out of sync with lexicon schemas.

The ERD has two categories of mismatches:

1. Namespace comments (lines 194, 204): Reference org.hypercerts.ontology.* but the actual lexicons use org.hypercerts.workscope.*

2. workScopeTag field names (lines 208-216): Use stale names that don't match tag.json:

   • label → should be name
   • kind? → should be category?
   • externalReference? → should be referenceDocument?

🛠️ Suggested fix

-' org.hypercerts.ontology.celExpression
+' org.hypercerts.workscope.cel
 dataclass celExpression {
     !if (SHOW_FIELDS == "true")
     expression
     usedTags[]
     version
     createdAt
     !endif
 }

-' org.hypercerts.ontology.workScopeTag
+' org.hypercerts.workscope.tag
 dataclass workScopeTag {
     !if (SHOW_FIELDS == "true")
     key
-    label
-    kind?
+    name
+    category?
     description?
     parent?
     status?
     supersededBy?
     aliases[]?
     sameAs[]?
-    externalReference?
+    referenceDocument?
     createdAt
     !endif
 }

As per coding guidelines: "When ERD.puml is modified, verify that all entities referenced correspond to lexicons in lexicons/**/*.json."

🤖 Prompt for AI Agents

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

In `@ERD.puml` around lines 194 - 219, Update the ERD to match the current
lexicons: change the namespace comments referencing org.hypercerts.ontology.* to
org.hypercerts.workscope.* for the dataclasses (e.g., celExpression and
workScopeTag) and rename the workScopeTag fields to match tag.json — replace
label with name, kind? with category?, and externalReference? with
referenceDocument?; then verify dataclass workScopeTag and celExpression match
the lexicon JSON field set and run the guideline check to ensure all ERD
entities correspond to lexicons/**/*.json.

🤖 Prompt for all review comments with AI agents

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

Duplicate comments:
In `@ERD.puml`:
- Around line 194-219: Update the ERD to match the current lexicons: change the
namespace comments referencing org.hypercerts.ontology.* to
org.hypercerts.workscope.* for the dataclasses (e.g., celExpression and
workScopeTag) and rename the workScopeTag fields to match tag.json — replace
label with name, kind? with category?, and externalReference? with
referenceDocument?; then verify dataclass workScopeTag and celExpression match
the lexicon JSON field set and run the guideline check to ensure all ERD
entities correspond to lexicons/**/*.json.

In `@README.md`:
- Around line 86-88: Replace the placeholder NSID in the workScope example so it
matches the actual schema: change the $type value in the workScope example
(workScope: { $type: "...#workScopeString", scope: "Environmental conservation"
}) to a concrete NSID used by the project (e.g.,
"org.hypercerts.workscope#workScopeString" or the exact NSID defined in your
JSON schema) so the README's workScopeString example is actionable and
copy/paste-ready.

---

ℹ️ 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 94d6937 and 075a6e5.

📒 Files selected for processing (9)

• .changeset/add-cel-work-scope-expressions.md
• ERD.puml
• README.md
• SCHEMAS.md
• lexicons/org/hypercerts/claim/activity.json
• lexicons/org/hypercerts/helper/workScopeTag.json
• lexicons/org/hypercerts/workscope/cel.json
• lexicons/org/hypercerts/workscope/tag.json
• scripts/generate-schemas.js

💤 Files with no reviewable changes (1)

• lexicons/org/hypercerts/helper/workScopeTag.json

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

• lexicons/org/hypercerts/workscope/cel.json
• lexicons/org/hypercerts/claim/activity.json
• .changeset/add-cel-work-scope-expressions.md
• scripts/generate-schemas.js