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..2fbd3e0 100644 --- a/pages/core-concepts/cel-work-scopes.md +++ b/pages/core-concepts/work-scopes.md @@ -1,21 +1,29 @@ --- -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](https://github.com/google/cel-spec) 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 + +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 The design uses two complementary layers: @@ -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 | |--------|-------------| @@ -219,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