From b5734c8015a60b262c79da3fb7b3862016a43a8f Mon Sep 17 00:00:00 2001 From: Sharfy Adamantine Date: Wed, 4 Mar 2026 02:49:32 +0800 Subject: [PATCH 1/3] docs: rename CEL Work Scopes to Work Scopes, trim speculative content, add simple case --- .../{cel-work-scopes.md => work-scopes.md} | 77 +++++++------------ 1 file changed, 28 insertions(+), 49 deletions(-) rename pages/core-concepts/{cel-work-scopes.md => work-scopes.md} (76%) diff --git a/pages/core-concepts/cel-work-scopes.md b/pages/core-concepts/work-scopes.md similarity index 76% rename from pages/core-concepts/cel-work-scopes.md rename to pages/core-concepts/work-scopes.md index 5df2b91..00ab3ae 100644 --- a/pages/core-concepts/cel-work-scopes.md +++ b/pages/core-concepts/work-scopes.md @@ -1,23 +1,31 @@ --- -title: CEL Work Scopes -description: How CEL (Common Expression Language) makes hypercert work scopes machine-readable, composable, and queryable. +title: Work Scopes +description: How work scopes make hypercerts machine-readable, composable, and queryable. --- -# CEL Work Scopes +# Work Scopes -Hypercert work scopes describe what work was done. A CEL expression alongside the human-readable work scope makes hypercerts machine-verifiable, composable, and queryable. +Work scopes describe what work a hypercert covers. Every activity claim has a `workScope` field that can be either a simple string list or a structured CEL expression for machine-evaluable logic. -[CEL (Common Expression Language)](https://github.com/google/cel-spec) is an open-source expression language built by Google for evaluating conditions in distributed systems. It's used by Kubernetes, Firebase, and Google Cloud IAM. +## The simple case -## Why structured scopes matter +Most hypercerts use a simple string list for work scopes: -A community in coastal Kenya mints a hypercert for "mangrove restoration and environmental education." A collective in Uganda creates one for "agroforestry with beekeeping." A drone operator in the Amazon documents "biodiversity monitoring in the Negro River region." These are all legible to a person reading them one at a time. They're invisible to any system trying to connect funders to relevant work at scale. +```json +{ + "workScope": { "allOf": ["Documentation", "Open Source"] } +} +``` -As the Hypercerts Protocol grows on ATProto — with actions, evaluations, and evidence living as persistent, portable records — the richer the network becomes, the harder it is to find, compare, validate, and compose claims when the most important field is unstructured text. +This is what the [Quickstart](/getting-started/quickstart) uses. It's human-readable and sufficient for many use cases. -## Architecture: two layers +## Why structured scopes matter -The design uses two complementary layers: +Simple string lists work for individual hypercerts, but they're hard to query at scale. As the network grows, connecting funders to relevant work, detecting overlapping claims, and matching evaluators to their domains all require machine-readable structure. Free-form text is legible to a person reading one claim at a time — it's invisible to any system trying to operate across thousands of claims. + +## CEL architecture + +[CEL (Common Expression Language)](https://github.com/google/cel-spec) is an open-source expression language for evaluating conditions in distributed systems. The design uses two complementary layers: 1. **Vocabulary layer** — `workScopeTag` records define what each tag *means* (e.g., what `mangrove_restoration` refers to, its description, hierarchy, and links to external ontologies). 2. **Composition layer** — `celExpression` objects compose those tags into evaluable logic on activity records (e.g., "this work includes mangrove restoration AND environmental education, AND is in Kenya"). @@ -129,49 +137,20 @@ The `workScope` field on `org.hypercerts.claim.activity` accepts two variants: ## What CEL unlocks -### Funder matching - -Funders can define their criteria as CEL expressions and the appview matches them against existing hypercerts: - -```cel -// "All mangrove work in East Africa" -scope.has("mangrove_restoration") && location.country in ["KE", "TZ", "MZ", "MG"] -``` +{% callout type="note" %} +The CEL evaluation runtime is planned. The lexicon schemas are defined, but appview-side evaluation is not yet implemented. +{% /callout %} -### Evaluation matching +Once the evaluation runtime is in place, structured scopes enable: -An auditor who verified mangrove survival rates can express applicability as a CEL condition, and the appview automatically matches it to relevant hypercerts: - -```cel -scope.has("mangrove_restoration") - && location.country == "KE" - && time.end >= timestamp("2025-01-01T00:00:00Z") -``` - -### Overlap detection - -When someone mints a new hypercert, CEL can check whether the claimed work scope overlaps with existing claims: - -```cel -existing.scope.overlaps(new.scope) - && existing.time.start < new.time.end - && new.time.start < existing.time.end - && existing.location.region == new.location.region -``` - -### Measurement-based queries - -Because CEL can access linked measurement records, funders can write queries that go beyond tags: - -```cel -// "Agroforestry that planted 500+ verified trees" -scope.has("agroforestry") - && measurements.exists(m, m.metric == "trees_planted" && m.value >= 500) -``` +- **Funder matching** — funders define criteria as CEL expressions, and the appview matches them against existing hypercerts automatically. +- **Evaluation matching** — evaluators express their domain expertise as CEL conditions, and the system surfaces relevant claims for review. +- **Overlap detection** — when a new hypercert is created, CEL can check whether the claimed work scope overlaps with existing claims in the same time and location. +- **Measurement-based queries** — because CEL can access linked measurement records, queries can go beyond tags (e.g., "agroforestry projects that planted 500+ verified trees"). ## CEL context schema (v1) -Every CEL expression evaluates against a typed context. Each variable maps to data already present in the activity record and its linked records. +This schema is planned — it defines the runtime context that appviews will provide when evaluating CEL expressions. Every CEL expression evaluates against a typed context. Each variable maps to data already present in the activity record and its linked records. | Variable | Type | Source | Description | |----------|------|--------|-------------| @@ -193,7 +172,7 @@ Every CEL expression evaluates against a typed context. Each variable maps to da ## Starter tag vocabulary -`workScopeTag` records are published as ATProto records that anyone can reference via strong references. [Certified](https://certified.ink) publishes curated tag sets for specific domains. Here's an example for regenerative work: +`workScopeTag` records are published as ATProto records that anyone can reference via strong references. [Certified](https://certified.app) publishes curated tag sets for specific domains. Here's an example for regenerative work: | Domain | Example tags | |--------|-------------| From a8d3f0ede6caf5b629a484dff5f189449523b073 Mon Sep 17 00:00:00 2001 From: Sharfy Adamantine Date: Wed, 4 Mar 2026 02:54:49 +0800 Subject: [PATCH 2/3] docs: restore original motivation paragraph for structured scopes --- pages/core-concepts/work-scopes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/core-concepts/work-scopes.md b/pages/core-concepts/work-scopes.md index 00ab3ae..e3a01a2 100644 --- a/pages/core-concepts/work-scopes.md +++ b/pages/core-concepts/work-scopes.md @@ -21,7 +21,7 @@ This is what the [Quickstart](/getting-started/quickstart) uses. It's human-read ## Why structured scopes matter -Simple string lists work for individual hypercerts, but they're hard to query at scale. As the network grows, connecting funders to relevant work, detecting overlapping claims, and matching evaluators to their domains all require machine-readable structure. Free-form text is legible to a person reading one claim at a time — it's invisible to any system trying to operate across thousands of claims. +Simple string lists work for individual hypercerts, but they're hard to query at scale. As the Hypercerts Protocol grows on ATProto — with actions, evaluations, and evidence living as persistent, portable records — the richer the network becomes, the harder it is to find, compare, validate, and compose claims when the most important field is unstructured text. ## CEL architecture From 9b17e83d52a7a7b533aeff805810b696bfb6e75c Mon Sep 17 00:00:00 2001 From: Sharfy Adamantine Date: Wed, 4 Mar 2026 02:55:44 +0800 Subject: [PATCH 3/3] docs: single CEL link in intro, remove redundant CEL links and paragraphs --- pages/core-concepts/work-scopes.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/pages/core-concepts/work-scopes.md b/pages/core-concepts/work-scopes.md index e3a01a2..2fbd3e0 100644 --- a/pages/core-concepts/work-scopes.md +++ b/pages/core-concepts/work-scopes.md @@ -5,7 +5,7 @@ description: How work scopes make hypercerts machine-readable, composable, and q # Work Scopes -Work scopes describe what work a hypercert covers. Every activity claim has a `workScope` field that can be either a simple string list or a structured CEL expression for machine-evaluable logic. +Work scopes describe what work a hypercert covers. Every activity claim has a `workScope` field that can be either a simple string list or a structured [CEL](https://github.com/google/cel-spec) expression for machine-evaluable logic. ## The simple case @@ -25,7 +25,7 @@ Simple string lists work for individual hypercerts, but they're hard to query at ## CEL architecture -[CEL (Common Expression Language)](https://github.com/google/cel-spec) is an open-source expression language for evaluating conditions in distributed systems. The design uses two complementary layers: +The design uses two complementary layers: 1. **Vocabulary layer** — `workScopeTag` records define what each tag *means* (e.g., what `mangrove_restoration` refers to, its description, hierarchy, and links to external ontologies). 2. **Composition layer** — `celExpression` objects compose those tags into evaluable logic on activity records (e.g., "this work includes mangrove restoration AND environmental education, AND is in Kenya"). @@ -198,6 +198,5 @@ CEL doesn't need to run onchain. The evaluation layer belongs alongside the ATPr ## Further reading -- [CEL specification](https://github.com/google/cel-spec) - [Core Data Model](/core-concepts/hypercerts-core-data-model) — how records connect - [Activity Claim lexicon](/lexicons/hypercerts-lexicons/activity-claim) — the `workScope` field in context