Green Goods Ontology

The formal specification of the Green Goods shared vocabulary: the entities the protocol tracks, the controlled vocabularies each layer spells its own way, the EAS schemas, the constraints the contracts enforce, and the lifecycle state machines. The source of truth is the machine-readable sidecar packages/shared/src/ontology/green-goods-ontology.json; this page is generated from it and CI fails when either drifts from the code.

The ontology currently declares 21 canonical concepts. Availability does not change a term's meaning.

Entities

Entity	Semantic status	Availability	Capability	Surfaces	Definition	Layers
Garden	canonical	available	implemented · deployed · active · integrated	admin · client · agent · public · docs	A community of gardeners rooted in a place, represented on-chain as an ERC-721 garden token whose ERC-6551 token-bound account holds the garden's treasury, role Hats, and metadata.	contracts · indexer (Garden) · shared · docs
Action	canonical	available	implemented · deployed · active · integrated	admin · client · agent · public · docs	A documented activity a gardener can perform — the unit of work template (e.g. "Plant native species", "Remove invasive growth").	contracts · indexer (Action) · shared · docs
Work	canonical	available	implemented · deployed · active · integrated	admin · client · agent · public · docs	One documented instance of an Action performed by a gardener — media, notes, and metadata submitted as an EAS Work attestation for steward review; approval records a separate Work Approval attestation.	contracts · shared · docs
Work Approval	canonical	available	implemented · deployed · active · integrated	admin · client · public · docs	The separate EAS attestation in which a garden steward records approval or rejection of a submitted Work, with feedback, confidence, and verification method. The Work record already exists; this decision never creates it.	contracts · shared · docs
Assessment	canonical	available	implemented · deployed · active · integrated	admin · client · public · docs	An up-front baseline and strategy for a garden — domain, diagnosis, SMART outcome targets, selected Actions, reporting period — authored by an evaluator or steward before work begins, mirrored to a Karma GAP milestone when that module is active; explicitly not a review of submitted Work (that is Work Approval).	contracts · shared · docs
Hypercert	canonical	in-build	implemented · deployed · inactive · partial	admin · client · public · docs	An on-chain claim of impact bundling approved Work into a fractional impact certificate. Funders hold fractions; gardeners hold contribution credit.	contracts · indexer (Hypercert) · shared · docs
Vault	canonical	available	implemented · deployed · active · integrated	admin · client · public · docs	A garden's endowment: one ERC-4626 vault per supported asset. Funders deposit and hold the vault's shares, which they can redeem, though a strategy or contract loss can reduce what comes back; the yield is donated onward, by default to the yield resolver, which splits it between the garden's Cookie Jar, Hypercert fraction purchases, and the GOODS treasury per configured ratios.	contracts · indexer (GardenVault) · shared · docs
Cookie Jar	canonical	available	implemented · deployed · active · integrated	admin · client · public · docs	A garden-scoped emergency or discretionary fund with rate-limited withdrawals. A garden's gardeners can claim from its jar within the configured cap, gated by the gardener Hat; a shared campaign jar admits the addresses on its allowlist instead.	contracts · indexer (CampaignCookieJar) · shared · docs
Attestation	canonical	available	implemented · deployed · active · integrated	admin · client · public · docs	An EAS (Ethereum Attestation Service) record. Used for Work submissions, Assessment outcomes, and other off-chain-verifiable claims.	contracts · shared · docs
Hat	canonical	available	implemented · deployed · active · integrated	admin · client · public · docs	A Hats Protocol role token. Determines on-chain authority — steward hats can approve Work; gardener hats can submit Work; evaluator hats can attest.	contracts · indexer (Garden) · shared · docs
Season	canonical	available	implemented · deployed · active · integrated	admin · client · agent · public · docs	A garden's main rhythm: a Season-type commitment cycle of the garden's pool, with a name, start and end dates, and the promises scoped to it. It stays a season at every stage, from planned to archived. A pool has at most one open Season at a time, and Campaigns may run beside it. It paces work and is never a countdown.	contracts · indexer (CommitmentCycle) · shared · docs
Need	canonical	planned	not-implemented · not-deployed · inactive · not-integrated	community · admin · client · public · docs	A community-authored statement of a place-based problem paired with a desired outcome. A Need can gather signals, moderation, linked commitments, and verified funding attribution without becoming a commitment or payment itself.	spec
Commitment Pool	canonical	available	implemented · deployed · active · integrated	admin · client · docs	A garden-anchored (or protocol root-garden) pool that registers, curates, and reconciles commitments under a charter.	contracts · indexer (CommitmentPool) · spec
Commitment Cycle	canonical	available	implemented · deployed · active · integrated	admin · client · docs	A bounded run of a pool — a Season or Campaign — seeded with timing and an immutable six-role allocation snapshot at open.	contracts · indexer (CommitmentCycle) · spec
Commitment Series	canonical	deployed-not-available	implemented · deployed · active · partial	admin · client · docs	The internal durable, pool-scoped identity for one Offer used over time. It groups ordinary Offer instances without creating obligations automatically, merging history across pools, or becoming a separate product noun.	contracts · indexer (CommitmentSeries) · spec
Commitment Provider Exposure	canonical	deployed-not-available	implemented · deployed · active · not-integrated	admin · client · docs	The current count of open commitments held by one accountable lead provider in one pool, derived only from self-describing register unit events.	indexer (CommitmentProviderExposure) · spec
Commitment Unit Summary	canonical	available	implemented · deployed · active · integrated	admin · client · docs	Exact-label pool or cycle totals for expected, approved, fulfilled, and open commitment units; unlike label hashes are never combined.	indexer (CommitmentUnitSummary) · spec
Commitment Series Cycle Summary	canonical	deployed-not-available	implemented · deployed · active · not-integrated	admin · client · docs	Current lifecycle counts for the instances of one commitment series within one cycle.	indexer (CommitmentSeriesCycleSummary) · spec
Commitment	canonical	available	implemented · deployed · active · integrated	admin · client · community · docs	A module-native promise record (offer or request) with one accountable lead, an optional contributor roster, repeatable action requirements, direction-aware confirmation, unit accounting in a non-transferable register, and evidence/work linkage — deliberately not an EAS attestation.	contracts · spec
Commitment Contributor	canonical	deployed-not-available	implemented · deployed · active · partial	admin · client · community · docs	A person on a commitment's roster whose approved Work or confirmed evidence can earn Hypercert recognition and a contributor payout; one roster member is the accountable lead.	contracts · spec
Commitment Payout Plan	canonical	deployed-not-available	implemented · deployed · active · partial	admin · client · docs	A garden-managed split of a fulfilled commitment's declared support into an explicit garden-retained amount and contributor child payouts. Its complete recognition vector is hash-bound, payment weights derive from amounts, and explicit finalization freezes it before dispatch.	contracts · indexer (CommitmentPayoutPlan) · shared · spec

Personas

Persona	Hat	Surfaces	Definition
Gardener	gardener	admin · client · agent · public · docs	A person doing regenerative Work in a garden. Submits Work, holds gardener Hats, receives credit toward Hypercerts and yield splits.
Steward	steward	admin · client · agent · public · docs	A person who stewards a garden — creates Actions, approves Work, configures Vault and Hat hierarchy. Holds the garden's steward Hats (the deployed Operator role).
Evaluator	evaluator	admin · client · public · docs	A person who authors or strengthens Assessments and attests impact methodology or outcomes. Evaluators do not approve or reject submitted Work; that authority belongs to stewards.
Funder	funder	admin · client · public · docs	A person or organization who funds a garden's work, from an individual or diaspora supporter to a grantmaker, institution, or crypto ecosystem fund. A funder donates to the garden's cookie jar, endows its vault, or backs the garden through a grant or partnership. A donation is a gift with nothing to withdraw. An endowment is a vault deposit the funder can redeem, less any strategy or contract loss; its yield is donated onward through the garden's configured splits, never paid to the funder. Giving needs no role; a steward or owner may grant the funder Hat, which makes its holder a garden member.
Community Member	community	client · public · docs	A local resident affected by a garden's Work. Signals or attests that Work exists and is healthy, and helps prioritize future Actions through public signal and conviction flows.

The on-chain hat tree has six roles; the Owner hat carries full garden control but has no dedicated persona — owners act through the steward surfaces.

Supporting terms

Technical terms kept in this Builders reference and deliberately excluded from the canonical entity and persona sets. Declaring them here preserves their meaning and published glossary links.

Term	Why it is not an entity
Domain	The `domain` controlled vocabulary — the four action domains — not an entity.
EAS (Ethereum Attestation Service)	The external attestation protocol; the record it produces is the Attestation entity.
Eight Forms of Capital	The impact framework behind the `capital` vocabulary, not an entity.
Impact Token	The broader tokenized-impact concept; the Green Goods implementation of it is Hypercert.
Indicator	The unit an outcome is measured in, carried inside Assessment fields rather than as its own record.
IPFS (InterPlanetary File System)	External storage protocol, referenced by CID from attestations.
Karma GAP (Grantee Accountability Protocol)	External reporting protocol, tracked in the integration matrix rather than the entity set.
MDR (Media-Details-Review)	The client's three-step submission workflow, not a domain record.
On-Chain	A property of where data lives, not something the protocol tracks.
Outcome	A SMART target held inside an Assessment, not a separate record.
Owner	A `garden-role` member with no dedicated persona — see personas_note.
Passkey	Authentication credential; account infrastructure, not domain vocabulary.
PWA (Progressive Web App)	A delivery surface, listed under Surfaces rather than entities.
Resolver	The contract that gates an attestation; declared per schema as `resolver`, not modeled as an entity.
Schema	The attestation template layer; the sidecar's `schemas` section is its canon.
Smart Account (Account Abstraction)	Wallet infrastructure, not domain vocabulary.

The canonical machine ordering is the Capital enum: Social (0), Material (1), Financial (2), Living (3), Intellectual (4), Experiential (5), Spiritual (6), Cultural (7).

Language policy

Product copy uses the declared terms and aliases. The vocabulary policy owns lint rules and admin/client prompt vocabulary; consult that source for the current lists.

Vocabularies

Each vocabulary has one canonical member list and a declared expected spelling per layer. The drift gate compares every representation against its source file; deviations are either declared here (layer conventions like the indexer's UNKNOWN sentinel) or recorded in the burn-down baseline.

capital

Eight Forms of Capital used to tag actions and assessments by the kind of value they create.

Canonical members: SOCIAL (0) · MATERIAL (1) · FINANCIAL (2) · LIVING (3) · INTELLECTUAL (4) · EXPERIENTIAL (5) · SPIRITUAL (6) · CULTURAL (7)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/registries/Action.sol · Capital	SOCIAL, MATERIAL, FINANCIAL, LIVING, INTELLECTUAL, EXPERIENTIAL, SPIRITUAL, CULTURAL
indexer	indexer	packages/indexer/schema.graphql · Capital	SOCIAL, MATERIAL, FINANCIAL, LIVING, INTELLECTUAL, EXPERIENTIAL, SPIRITUAL, CULTURAL, UNKNOWN	UNKNOWN is the indexer's permanent fallback sentinel for unmapped on-chain values — declared, not drift.
shared-enum	shared	packages/shared/src/types/domain.ts · Capital	SOCIAL=0, MATERIAL=1, FINANCIAL=2, LIVING=3, INTELLECTUAL=4, EXPERIENTIAL=5, SPIRITUAL=6, CULTURAL=7
capital-type	shared	packages/shared/src/types/hypercerts.ts · CapitalType	social, material, financial, living, intellectual, experiential, spiritual, cultural	Ordered deliberately: the union is declared here in canonical machine order because index-based bridges between Capital and CapitalType lists are a live bug risk. The current file deviates (living-first presentational order) — baselined until reordered or a mapping function lands.

• Mapping capital-enum-to-capital-type (shared-enum → capital-type; explicit; total; bijective): SOCIAL → social, MATERIAL → material, FINANCIAL → financial, LIVING → living, INTELLECTUAL → intellectual, EXPERIENTIAL → experiential, SPIRITUAL → spiritual, CULTURAL → cultural.
  • Code anchor: none — no runtime mapping function exists yet.
  • No runtime mapping function exists yet — see known_issues.missing-capital-mapping-fn.

domain

Category of regenerative work — where the work happens. Four production domains; a domain is neither an outcome nor a capital.

Canonical members: SOLAR (0) · AGRO (1) · EDU (2) · WASTE (3)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/registries/Action.sol · Domain	SOLAR, AGRO, EDU, WASTE
indexer	indexer	packages/indexer/schema.graphql · Domain	SOLAR, AGRO, EDU, WASTE, UNKNOWN	UNKNOWN is the indexer's permanent fallback sentinel — declared, not drift.
shared-enum	shared	packages/shared/src/types/domain.ts · Domain	SOLAR=0, AGRO=1, EDU=2, WASTE=3
action-domain	shared	packages/shared/src/types/hypercerts.ts · ActionDomain	solar, waste, agroforestry, education	Long-form lowercase spellings used in hypercert metadata. Mutual credit was retired as a domain on 2026-10-18; commitment pooling and promises serve that need. Hypercert metadata minted before then may carry mutual_credit, which only meant that none of the bundled work named a domain.
slug-prefix	shared	packages/shared/src/hooks/action/useActionForm.ts · DOMAIN_SLUG_PREFIX	solar, agro, edu, waste	Short lowercase prefixes baked into immutable on-chain action slugs (agro., edu.).

• Mapping domain-to-action-domain (solidity → action-domain; explicit; total; bijective): SOLAR → solar, AGRO → agroforestry, EDU → education, WASTE → waste.

  • Code anchor: packages/shared/src/modules/data/hypercerts-filters.ts

• Mapping action-domain-vs-slug-prefix (action-domain → slug-prefix; identity; partial): identity (same spelling on both sides).

  • Code anchor: none — no runtime mapping function exists yet.
  • The two lowercase spellings of the same domain must converge on one word per member; agroforestry/education vs agro/edu currently diverge — baselined.

garden-role

The six per-garden Hats roles that gate every protocol permission. The enum member name is compile-time only — GardenRole never appears in the ABI, so callers pass the pinned index.

Canonical members: Gardener (0) · Evaluator (1) · Steward (2) · Owner (3) · Funder (4) · Community (5)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/IHatsModule.sol · GardenRole	Gardener, Evaluator, Steward, Owner, Funder, Community
shared-ids	shared	packages/shared/src/utils/blockchain/garden-roles.ts · GARDEN_ROLE_IDS	gardener=0, evaluator=1, steward=2, owner=3, funder=4, community=5	Key order and numeric ids must track the Solidity enum exactly — these ids go into contract calls.

transfer-restriction

Garden NFT transfer mode.

Canonical members: Unrestricted (0) · OwnerOnly (1) · Locked (2)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/tokens/Garden.sol · TransferRestriction	Unrestricted, OwnerOnly, Locked

badge-rule

GreenWill badge eligibility rule kinds, proven from on-chain state at claim time.

Canonical members: None (0) · Hat (1) · WorkAttestation (2) · VaultShares (3)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/registries/GreenWill.sol · BadgeRule	None, Hat, WorkAttestation, VaultShares

ens-name-type

Kind of *.greengoods.eth subname being registered.

Canonical members: Gardener (0) · Garden (1)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/registries/ENS.sol · NameType	Gardener, Garden

weight-scheme

Conviction-voting weight scheme selected immutably at garden mint.

Canonical members: Linear (0) · Exponential (1) · Power (2)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/IGardensModule.sol · WeightScheme	Linear, Exponential, Power
indexer	indexer	packages/indexer/schema.graphql · WeightScheme	LINEAR, EXPONENTIAL, POWER
shared	shared	packages/shared/src/types/gardens-community.ts · WeightScheme	Linear=0, Exponential=1, Power=2	Genuine raw uint8 decode path (Number(weightSchemeRaw) as WeightScheme) — ordering is load-bearing and correct.

signal-pool-type

Name collision

Solidity carries two unrelated PoolType enums: the live Gardens V2 signal-pool vocabulary (signal-pool-type, ActionSignal/HypercertSignal) and the commitment-pooling anchor vocabulary (commitment-pool-type, Garden/Protocol). They are separate vocabularies in this ontology — never merge or cross-map them.

Kind of Gardens V2 conviction signal pool attached to a garden. Distinct from the commitment-pooling PoolType (Garden/Protocol) — same Solidity identifier, different vocabulary; never merge them.

Canonical members: ActionSignal (0) · HypercertSignal (1)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/IGardensModule.sol · PoolType	ActionSignal, HypercertSignal
indexer	indexer	packages/indexer/schema.graphql · PoolType	ACTION_SIGNAL, HYPERCERT_SIGNAL	Currently {HYPERCERT, ACTION} — inverted vs chain and referenced by zero entity fields (dead surface). Baselined; fix direction is deletion or correction alongside the shared enum.
shared	shared	packages/shared/src/types/gardens-community.ts · PoolType	ActionSignal=0, HypercertSignal=1	Currently {Hypercert = 0, Action = 1} — inverted vs chain. Verified latent, not live: pool types are assigned by address identity (annotateGardenSignalPools), never decoded from a raw uint8. Baselined with a mandatory blast-radius re-check before burn-down.

vault-event-type

Vault history event kinds recorded by the indexer.

Canonical members: DEPOSIT · WITHDRAW · HARVEST · EMERGENCY_PAUSED

Representation	Layer	Source	Expected members	Note
indexer	indexer	packages/indexer/schema.graphql · VaultEventType	DEPOSIT, WITHDRAW, HARVEST, EMERGENCY_PAUSED
shared	shared	packages/shared/src/types/vaults.ts · VaultEventType	DEPOSIT, WITHDRAW, HARVEST, EMERGENCY_PAUSED

hypercert-status

Lifecycle status of an indexed hypercert.

Canonical members: ACTIVE · CLAIMED · SOLD · UNKNOWN

Representation	Layer	Source	Expected members	Note
indexer	indexer	packages/indexer/schema.graphql · HypercertStatus	ACTIVE, CLAIMED, SOLD, UNKNOWN	SOLD is declared but never assigned by any handler (marketplace is outside the indexing boundary).
shared	shared	packages/shared/src/types/hypercerts.ts · HypercertStatus	active, claimed, sold, unknown

hypercert-bundle-kind

Metadata discriminator separating legacy Work bundles from commitment-backed Hypercert bundles.

Canonical members: WORK_LEGACY · COMMITMENT

Representation	Layer	Source	Expected members	Note
indexer	indexer	packages/indexer/schema.graphql · HypercertBundleKind	WORK_LEGACY, COMMITMENT
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · HypercertBundleKind	WORK_LEGACY, COMMITMENT

work-display-status

Canonical display status for work items across the UI — protocol states plus client-derived offline/sync states.

Canonical members: approved · rejected · pending · syncing · uploading · sync_failed · offline

Representation	Layer	Source	Expected members	Note
shared-union	shared	packages/shared/src/types/domain.ts · WorkDisplayStatus	approved, rejected, pending, syncing, uploading, sync_failed, offline
enhanced-work-approval	shared	packages/shared/src/hooks/work/useWorkApprovals.ts · EnhancedWorkApproval.status	approved, rejected, pending, syncing, uploading, sync_failed, offline	Declared as the canonical union; the current file carries a divergent five-value list (failed instead of sync_failed; missing uploading/offline) — baselined.
offline-work-item	shared	packages/shared/src/types/offline.ts · OfflineWorkItem.status	approved, rejected, pending, syncing, uploading, sync_failed, offline	Declared as the canonical union; the current file carries a divergent four-value list — baselined pending status-union consolidation.
hypercert-sync-status	shared	packages/shared/src/hooks/hypercerts/useHypercerts.ts · HypercertSyncStatus	approved, rejected, pending, syncing, uploading, sync_failed, offline	Declared as the canonical union; the current file carries a divergent four-value sync list — baselined pending status-union consolidation.

cynefin-phase

Cynefin complexity phase classifying an assessment's operating environment.

Canonical members: CLEAR (0) · COMPLICATED (1) · COMPLEX (2) · CHAOTIC (3)

Representation	Layer	Source	Expected members	Note
shared	shared	packages/shared/src/types/domain.ts · CynefinPhase	CLEAR=0, COMPLICATED=1, COMPLEX=2, CHAOTIC=3

confidence

Four-value verification confidence carried on work approvals (on-chain uint8, bounded to 3).

Canonical members: NONE (0) · LOW (1) · MEDIUM (2) · HIGH (3)

Representation	Layer	Source	Expected members	Note
shared	shared	packages/shared/src/types/domain.ts · Confidence	NONE=0, LOW=1, MEDIUM=2, HIGH=3

verification-method

Verification method bitmask flags on work approvals (uint8, bounded to 15).

Canonical members: HUMAN · IOT · ONCHAIN · AGENT

Values are explicit (not index-derived) for this vocabulary.

Representation	Layer	Source	Expected members	Note
shared	shared	packages/shared/src/types/domain.ts · VerificationMethod	HUMAN=1, IOT=2, ONCHAIN=4, AGENT=8	Bitmask members declared with shift expressions (1 << n) in source; the extractor evaluates them.

action-type

Action archetype tags used in hypercert metadata and filtering.

Canonical members: hub_session · workshop · node_deployment · cleanup · recycling · composting · planting · nursery · maintenance · training · certification · commitment · exchange

Representation	Layer	Source	Expected members	Note
shared	shared	packages/shared/src/types/hypercerts.ts · ActionType	hub_session, workshop, node_deployment, cleanup, recycling, composting, planting, nursery, maintenance, training, certification, commitment, exchange

job-kind

Offline job-queue mutation kinds (the write-ahead ledger's vocabulary).

Canonical members: work · approval · commitmentSeries · commitment · claim · evidence · workLink · confirmation

Representation	Layer	Source	Expected members	Note
shared	shared	packages/shared/src/types/job-queue.ts · JobKindMap	work, approval, commitmentSeries, commitment, claim, evidence, workLink, confirmation

commitment-pool-type

Name collision

Solidity carries two unrelated PoolType enums: the live Gardens V2 signal-pool vocabulary (signal-pool-type, ActionSignal/HypercertSignal) and the commitment-pooling anchor vocabulary (commitment-pool-type, Garden/Protocol). They are separate vocabularies in this ontology — never merge or cross-map them.

Commitment-pooling pool anchor kind. Name-collides with the live Gardens V2 signal-pool PoolType — the sidecar keeps them as separate vocabularies on purpose.

Canonical members: Garden (0) · Protocol (1)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · PoolType	Garden, Protocol
indexer	indexer	packages/indexer/schema.graphql · CommitmentPoolType	UNKNOWN, GARDEN, PROTOCOL	UNKNOWN represents the Solidity sentinel or unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentPoolType	UNKNOWN, GARDEN, PROTOCOL

pool-state

Commitment pool lifecycle — every state is on-chain.

Canonical members: None (0) · NotReady (1) · Ready (2) · Open (3) · Paused (4) · Closed (5) · Composted (6)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · PoolState	None, NotReady, Ready, Open, Paused, Closed, Composted
indexer	indexer	packages/indexer/schema.graphql · CommitmentPoolState	UNKNOWN, NOT_READY, READY, OPEN, PAUSED, CLOSED, COMPOSTED	UNKNOWN represents the Solidity None sentinel and unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentPoolState	UNKNOWN, NOT_READY, READY, OPEN, PAUSED, CLOSED, COMPOSTED

cycle-type

Cycle kinds: one open Season per pool; Campaigns may overlap.

Canonical members: Season (0) · Campaign (1)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · CycleType	Season, Campaign
indexer	indexer	packages/indexer/schema.graphql · CommitmentCycleType	UNKNOWN, SEASON, CAMPAIGN	UNKNOWN represents the Solidity sentinel or unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentCycleType	UNKNOWN, SEASON, CAMPAIGN

cycle-state

On-chain cycle states; Draft lives in app IndexedDB and InProgress/Reviewing are derived from events.

Canonical members: None (0) · Seeded (1) · Open (2) · Reconciled (3) · Composted (4) · Cancelled (5)

Derived states (never stored): Draft · InProgress · Reviewing

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · CycleState	None, Seeded, Open, Reconciled, Composted, Cancelled
indexer	indexer	packages/indexer/schema.graphql · CommitmentCycleState	UNKNOWN, SEEDED, OPEN, RECONCILED, COMPOSTED, CANCELLED	UNKNOWN represents the Solidity None sentinel and unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentCycleState	UNKNOWN, SEEDED, OPEN, RECONCILED, COMPOSTED, CANCELLED

commitment-direction

Whether a commitment offers capacity or requests it; drives the direction-aware default confirmer.

Canonical members: Offer (0) · Request (1)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · CommitmentDirection	Offer, Request
indexer	indexer	packages/indexer/schema.graphql · CommitmentDirection	UNKNOWN, OFFER, REQUEST	UNKNOWN represents the Solidity sentinel or unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentDirection	UNKNOWN, OFFER, REQUEST

commitment-type

Commitment archetypes; DomainImpact keeps the full Work → WorkApproval path, the others confirm via counterparty.

Canonical members: DomainImpact (0) · SupportService (1) · SeasonCampaign (2) · StewardCaptured (3)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · CommitmentType	DomainImpact, SupportService, SeasonCampaign, StewardCaptured
indexer	indexer	packages/indexer/schema.graphql · CommitmentKind	UNKNOWN, DOMAIN_IMPACT, SUPPORT_SERVICE, SEASON_CAMPAIGN, STEWARD_CAPTURED	UNKNOWN represents the Solidity sentinel or unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentKind	UNKNOWN, DOMAIN_IMPACT, SUPPORT_SERVICE, SEASON_CAMPAIGN, STEWARD_CAPTURED

commitment-state

On-chain commitment states; Draft is app-side and Active/EvidenceSubmitted/PartiallyApproved/Reconciled are derived from module events.

Canonical members: None (0) · Offered (1) · Requested (2) · Accepted (3) · ReadyForConfirmation (4) · Fulfilled (5) · Cancelled (6) · Expired (7) · Disputed (8)

Derived states (never stored): Draft · Active · EvidenceSubmitted · PartiallyApproved · Reconciled

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · CommitmentState	None, Offered, Requested, Accepted, ReadyForConfirmation, Fulfilled, Cancelled, Expired, Disputed
indexer	indexer	packages/indexer/schema.graphql · CommitmentOnchainState	UNKNOWN, OFFERED, REQUESTED, ACCEPTED, READY_FOR_CONFIRMATION, FULFILLED, CANCELLED, EXPIRED, DISPUTED	UNKNOWN represents the Solidity None sentinel and unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentOnchainState	UNKNOWN, OFFERED, REQUESTED, ACCEPTED, READY_FOR_CONFIRMATION, FULFILLED, CANCELLED, EXPIRED, DISPUTED

claim-type

Immutable claimant-eligibility class set at commitment creation; runtime claim kind must equal it.

Canonical members: Garden (0) · Individual (1)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · ClaimType	Garden, Individual
indexer	indexer	packages/indexer/schema.graphql · CommitmentClaimType	UNKNOWN, GARDEN, INDIVIDUAL	UNKNOWN represents the Solidity sentinel or unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentClaimType	UNKNOWN, GARDEN, INDIVIDUAL

contributor-policy

How contributor membership is established before the commitment roster freezes.

Canonical members: Open (0) · LeadManaged (1)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · ContributorPolicy	Open, LeadManaged
indexer	indexer	packages/indexer/schema.graphql · CommitmentContributorPolicy	UNKNOWN, OPEN, LEAD_MANAGED	UNKNOWN represents the Solidity sentinel or unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentContributorPolicy	UNKNOWN, OPEN, LEAD_MANAGED

claim-mode

Whether claiming transitions immediately (Open) or awaits steward acceptance (ApprovalGated).

Canonical members: Open (0) · ApprovalGated (1)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · ClaimMode	Open, ApprovalGated
indexer	indexer	packages/indexer/schema.graphql · CommitmentClaimMode	UNKNOWN, OPEN, APPROVAL_GATED	UNKNOWN represents the Solidity sentinel or unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentClaimMode	UNKNOWN, OPEN, APPROVAL_GATED

dispute-resolution

Steward-only dispute outcomes; RestorePrevious replays the stored pre-dispute state.

Canonical members: RestorePrevious (0) · Fulfilled (1) · Cancelled (2) · Expired (3)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · DisputeResolution	RestorePrevious, Fulfilled, Cancelled, Expired

consideration-rail

Consideration reference rail: ArbitrumExternal records steward-paid jar/treasury payments; CeloSettlement is consumed only by the SettlementModule. Direction is carried by Commitment.payerGarden, not by the rail.

Canonical members: None (0) · ArbitrumExternal (1) · CeloSettlement (2)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · ConsiderationRail	None, ArbitrumExternal, CeloSettlement
indexer	indexer	packages/indexer/schema.graphql · CommitmentConsiderationRail	UNKNOWN, NONE, ARBITRUM_EXTERNAL, CELO_SETTLEMENT	UNKNOWN represents the Solidity sentinel or unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentConsiderationRail	UNKNOWN, NONE, ARBITRUM_EXTERNAL, CELO_SETTLEMENT

accounting-state

CommitmentRegistry unit-class accounting states (non-transferable, ERC-1155-style).

Canonical members: Registered (0) · Committed (1) · Released (2) · Fulfilled (3)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentRegistry.sol · AccountingState	Registered, Committed, Released, Fulfilled

commitment-payout-plan-status

Derived progress of a frozen commitment payout plan across its contributor child disbursements.

Canonical members: Draft (0) · Pending (1) · Partial (2) · Complete (3) · Failed (4)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ISettlementModule.sol · PayoutPlanStatus	Draft, Pending, Partial, Complete, Failed
indexer	indexer	packages/indexer/schema.graphql · CommitmentPayoutPlanStatus	DRAFT, PENDING, PARTIAL, COMPLETE, FAILED

confirmation-path

The authority path that produced fulfillment provenance. PoolFallback is local-garden authority; ProtocolFallback is an explicitly selected Green Goods protocol-garden authority.

Canonical members: Ordinary (0) · PoolFallback (1) · ProtocolFallback (2)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · ConfirmationPath	Ordinary, PoolFallback, ProtocolFallback
indexer	indexer	packages/indexer/schema.graphql · CommitmentConfirmationPath	UNKNOWN, ORDINARY, POOL_FALLBACK, PROTOCOL_FALLBACK	UNKNOWN represents the Solidity sentinel or unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentConfirmationPath	UNKNOWN, ORDINARY, POOL_FALLBACK, PROTOCOL_FALLBACK

disbursement-state

Settlement disbursement lifecycle. The GraphQL mirror prepends UNKNOWN and otherwise preserves the Solidity states.

Canonical members: None (0) · Queued (1) · Dispatched (2) · Confirmed (3) · Failed (4) · Cancelled (5)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ISettlementModule.sol · DisbursementState	None, Queued, Dispatched, Confirmed, Failed, Cancelled
indexer	indexer	packages/indexer/schema.graphql · DisbursementState	UNKNOWN, QUEUED, DISPATCHED, CONFIRMED, FAILED, CANCELLED	UNKNOWN represents the Solidity None sentinel and unexpected values.

disbursement-kind

Purpose of an outbound settlement entry. ContributorConsideration and GardenBeneficiary are the two immutable provider-payment shapes; LoanPrincipal is the records-only Commitment Credit companion shape; Refund returns a steward-confirmed member deposit from the garden Safe through the ordinary settlement rail.

Canonical members: ContributorConsideration (0) · Funding (1) · LoanPrincipal (2) · GardenBeneficiary (3) · Refund (4)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ISettlementModule.sol · DisbursementKind	ContributorConsideration, Funding, LoanPrincipal, GardenBeneficiary, Refund
indexer	indexer	packages/indexer/schema.graphql · DisbursementKind	UNKNOWN, CONTRIBUTOR_CONSIDERATION, FUNDING, LOAN_PRINCIPAL, GARDEN_BENEFICIARY, REFUND	UNKNOWN is the indexer's fail-closed fallback for unmapped values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · DisbursementKind	UNKNOWN, CONTRIBUTOR_CONSIDERATION, FUNDING, LOAN_PRINCIPAL, GARDEN_BENEFICIARY, REFUND

funding-route

Typed funding route for non-commitment settlement entries; ProtocolToGarden is the only initial route.

Canonical members: None (0) · ProtocolToGarden (1)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ISettlementModule.sol · FundingRoute	None, ProtocolToGarden
indexer	indexer	packages/indexer/schema.graphql · FundingRoute	UNKNOWN, NONE, PROTOCOL_TO_GARDEN	UNKNOWN is the indexer's fail-closed fallback for unmapped values.

funding-state

Lifecycle of one member-funded priced-Offer claim. Pledged records intent; DepositRecorded records the full steward-confirmed Safe deposit; Consumed binds it to the accepted claimant; Closed follows completed delivery; RefundQueued and Refunded reuse one persistent settlement child; Withdrawn means no recorded deposit was owed.

Canonical members: None (0) · Pledged (1) · DepositRecorded (2) · Consumed (3) · Closed (4) · RefundQueued (5) · Refunded (6) · Withdrawn (7)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ISettlementModule.sol · FundingState	None, Pledged, DepositRecorded, Consumed, Closed, RefundQueued, Refunded, Withdrawn
indexer	indexer	packages/indexer/schema.graphql · FundingState	UNKNOWN, PLEDGED, DEPOSIT_RECORDED, CONSUMED, CLOSED, REFUND_QUEUED, REFUNDED, WITHDRAWN	UNKNOWN represents the Solidity None sentinel and unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · FundingState	UNKNOWN, PLEDGED, DEPOSIT_RECORDED, CONSUMED, CLOSED, REFUND_QUEUED, REFUNDED, WITHDRAWN

commitment-settlement-flow

Read-model direction derived from immutable payer and provider gardens plus the write-once protocol garden. It describes Green Goods settlement intent, not observation of later Celo token circulation.

Canonical members: Internal · ProtocolToGarden · GardenToProtocol · GardenToGarden

Representation	Layer	Source	Expected members	Note
indexer	indexer	packages/indexer/schema.graphql · CommitmentSettlementFlow	UNKNOWN, INTERNAL, PROTOCOL_TO_GARDEN, GARDEN_TO_PROTOCOL, GARDEN_TO_GARDEN	UNKNOWN is retained until the protocol garden configuration is observed.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentSettlementFlow	UNKNOWN, INTERNAL, PROTOCOL_TO_GARDEN, GARDEN_TO_PROTOCOL, GARDEN_TO_GARDEN

loan-state

Records-only pool-credit loan lifecycle: Requested → Approved → Disbursed → Repaid, with recoverable Defaulted and pre-disbursement Cancelled. Default is not terminal — later repayment records LoanRepaid(recoveredFromDefault). The Repaying overlay is derived by shared consumers from indexed repayment amounts while repayment sits between zero and principal + feeAmount and is never stored as a contract or indexer hard state.

Canonical members: None (0) · Requested (1) · Approved (2) · Disbursed (3) · Repaid (4) · Defaulted (5) · Cancelled (6)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICreditRegistry.sol · LoanState	None, Requested, Approved, Disbursed, Repaid, Defaulted, Cancelled
indexer	indexer	packages/indexer/schema.graphql · LoanState	REQUESTED, APPROVED, DISBURSED, REPAID, DEFAULTED, CANCELLED
shared	shared	packages/shared/src/modules/commitment-pooling/types-credit.ts · LoanState	REQUESTED, APPROVED, DISBURSED, REPAID, DEFAULTED, CANCELLED

loan-rail

Disbursement rail recorded on a loan and projected by the CreditRegistry indexer read model. Jar and Treasury are steward-attested Arbitrum-side records; GDollarSettlement binds the loan to its one Confirmed SettlementModule LoanPrincipal child. Repayment recording is Jar/Treasury only — the G$ rail reverts GDollarRepaymentDisabled until a bounded authenticated receipt policy clears its gates.

Canonical members: None (0) · Jar (1) · Treasury (2) · GDollarSettlement (3)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICreditRegistry.sol · LoanRail	None, Jar, Treasury, GDollarSettlement
indexer	indexer	packages/indexer/schema.graphql · LoanRail	NONE, JAR, TREASURY, GDOLLAR_SETTLEMENT
shared	shared	packages/shared/src/modules/commitment-pooling/types-credit.ts · LoanRail	NONE, JAR, TREASURY, GDOLLAR_SETTLEMENT

failure-code

Stored settlement failure taxonomy used for deterministic recovery and steward rendering.

Canonical members: None (0) · GardenRouteUnavailable (1) · InvalidRecipient (2) · BatchSizeExceeded (3) · TransferAmountExceeded (4) · BatchAmountExceeded (5) · PeriodCapExceeded (6) · RouteRejected (7) · RouteReverted (8) · UnsupportedReceiverPaysFee (9) · FeeQuoteExceeded (10) · BalanceDeltaMismatch (11) · SourceStranded (12)

Representation	Layer	Source	Expected members	Note
source-solidity	solidity	packages/contracts/src/interfaces/ISettlementModule.sol · FailureCode	None, GardenRouteUnavailable, InvalidRecipient, BatchSizeExceeded, TransferAmountExceeded, BatchAmountExceeded, PeriodCapExceeded, RouteRejected, RouteReverted, UnsupportedReceiverPaysFee, FeeQuoteExceeded, BalanceDeltaMismatch, SourceStranded
executor-solidity	solidity	packages/contracts/src/interfaces/ICeloSettlementExecutor.sol · FailureCode	None, GardenRouteUnavailable, InvalidRecipient, BatchSizeExceeded, TransferAmountExceeded, BatchAmountExceeded, PeriodCapExceeded, RouteRejected, RouteReverted, UnsupportedReceiverPaysFee, FeeQuoteExceeded, BalanceDeltaMismatch

• Mapping executor-failure-codes-to-source (executor-solidity → source-solidity; identity; total; unmapped on the right: SourceStranded): identity (same spelling on both sides).
  • Code anchor: none — no runtime mapping function exists yet.
  • SourceStranded is a source-only recovery disposition and is never accepted from the executor over CCIP.

result-status

Celo executor result stored in Solidity; GraphQL exposes the same outcomes as SettlementExecutionStatus with an UNKNOWN sentinel.

Canonical members: None (0) · Success (1) · Failed (2)

Representation	Layer	Source	Expected members	Note
executor-solidity	solidity	packages/contracts/src/interfaces/ICeloSettlementExecutor.sol · ResultStatus	None, Success, Failed

acknowledgment-deferral-code

Why an executor acknowledgment could not be sent immediately without changing the stored execution result.

Canonical members: None (0) · QuoteFailed (1) · FeeReserveLow (2) · SendFailed (3)

Representation	Layer	Source	Expected members	Note
executor-solidity	solidity	packages/contracts/src/interfaces/ICeloSettlementExecutor.sol · AcknowledgmentDeferralCode	None, QuoteFailed, FeeReserveLow, SendFailed

settlement-execution-status

GraphQL execution-result mirror with an explicit UNKNOWN sentinel.

Canonical members: UNKNOWN · SUCCESS · FAILED

Representation	Layer	Source	Expected members	Note
indexer	indexer	packages/indexer/schema.graphql · SettlementExecutionStatus	UNKNOWN, SUCCESS, FAILED

commitment-claim-request-state

Indexer lifecycle of a commitment claim request, including peer supersession after one request is accepted.

Canonical members: PENDING · ACCEPTED · DECLINED · SUPERSEDED

Representation	Layer	Source	Expected members	Note
indexer	indexer	packages/indexer/schema.graphql · CommitmentClaimRequestState	PENDING, ACCEPTED, DECLINED, SUPERSEDED
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentClaimRequestState	PENDING, ACCEPTED, DECLINED, SUPERSEDED

commitment-event-type

Normalized event vocabulary for commitment-pooling history and read-model aggregation.

Canonical members: MODULE_UPDATED · MODULE_DEPENDENCY_UPDATED · MODULE_SCHEMA_UID_UPDATED · MODULE_PAUSE_STATUS_CHANGED · POOL_REGISTERED · POOL_CHARTER_UPDATED · POOL_READY · POOL_OPENED · POOL_PAUSED · POOL_RESUMED · POOL_CLOSED · POOL_COMPOSTED · POOL_REOPENED · CLASS_REGISTERED · PROVIDER_OPEN_COMMITMENT_CAP_UPDATED · CYCLE_SEEDED · CYCLE_OPENED · CYCLE_CLOSED · CYCLE_COMPOSTED · CYCLE_CANCELLED · CREATED · CONSIDERATION_DECLARED · VALUE_DECLARED · CONFIRMER_RULE_SET · CLAIM_REQUESTED · CLAIM_DECLINED · ACCEPTED · EXCHANGE_ACCEPTED · COMMITMENT_SERIES_CREATED · COMMITMENT_SERIES_METADATA_UPDATED · COMMITMENT_SERIES_RESTED · COMMITMENT_SERIES_RESUMED · COMMITMENT_SERIES_RETIRED · CONTRIBUTOR_ADDED · CONTRIBUTOR_REMOVED · CONTRIBUTOR_REQUIREMENT_ASSIGNED · CONTRIBUTOR_ROSTER_FROZEN · WORK_LINKED · WORK_UNLINKED · APPROVED_WORK_COUNTED · APPROVED_WORK_REVERSED · EVIDENCE_ATTACHED · ASSESSMENT_ATTACHED · READY_FOR_CONFIRMATION · CONFIRMATION_RECORDED · FULFILLED · CANCELLED · EXPIRED · DISPUTED · DISPUTE_RESOLVED · CONSIDERATION_PAID · UNITS_COMMITTED · UNITS_RELEASED · UNITS_FULFILLED · FUNDING_PLEDGED · FUNDING_DEPOSIT_RECORDED · FUNDING_CONSUMED · FUNDING_WITHDRAWN

Representation	Layer	Source	Expected members	Note
indexer	indexer	packages/indexer/schema.graphql · CommitmentEventType	MODULE_UPDATED, MODULE_DEPENDENCY_UPDATED, MODULE_SCHEMA_UID_UPDATED, MODULE_PAUSE_STATUS_CHANGED, POOL_REGISTERED, POOL_CHARTER_UPDATED, POOL_READY, POOL_OPENED, POOL_PAUSED, POOL_RESUMED, POOL_CLOSED, POOL_COMPOSTED, POOL_REOPENED, CLASS_REGISTERED, PROVIDER_OPEN_COMMITMENT_CAP_UPDATED, CYCLE_SEEDED, CYCLE_OPENED, CYCLE_CLOSED, CYCLE_COMPOSTED, CYCLE_CANCELLED, CREATED, CONSIDERATION_DECLARED, VALUE_DECLARED, CONFIRMER_RULE_SET, CLAIM_REQUESTED, CLAIM_DECLINED, ACCEPTED, EXCHANGE_ACCEPTED, COMMITMENT_SERIES_CREATED, COMMITMENT_SERIES_METADATA_UPDATED, COMMITMENT_SERIES_RESTED, COMMITMENT_SERIES_RESUMED, COMMITMENT_SERIES_RETIRED, CONTRIBUTOR_ADDED, CONTRIBUTOR_REMOVED, CONTRIBUTOR_REQUIREMENT_ASSIGNED, CONTRIBUTOR_ROSTER_FROZEN, WORK_LINKED, WORK_UNLINKED, APPROVED_WORK_COUNTED, APPROVED_WORK_REVERSED, EVIDENCE_ATTACHED, ASSESSMENT_ATTACHED, READY_FOR_CONFIRMATION, CONFIRMATION_RECORDED, FULFILLED, CANCELLED, EXPIRED, DISPUTED, DISPUTE_RESOLVED, CONSIDERATION_PAID, UNITS_COMMITTED, UNITS_RELEASED, UNITS_FULFILLED, FUNDING_PLEDGED, FUNDING_DEPOSIT_RECORDED, FUNDING_CONSUMED, FUNDING_WITHDRAWN

commitment-unit-scope

Read-model grouping boundary for exact-label commitment-unit summaries.

Canonical members: POOL · CYCLE

Representation	Layer	Source	Expected members	Note
indexer	indexer	packages/indexer/schema.graphql · CommitmentUnitScope	POOL, CYCLE
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentUnitScope	POOL, CYCLE

commitment-series-state

Lifecycle of the internal durable identity for one Offer used over time in one pool. Retired is terminal; instance lifecycles remain independent.

Canonical members: None (0) · Active (1) · Resting (2) · Retired (3)

Representation	Layer	Source	Expected members	Note
solidity	solidity	packages/contracts/src/interfaces/ICommitmentPoolingModule.sol · CommitmentSeriesState	None, Active, Resting, Retired
indexer	indexer	packages/indexer/schema.graphql · CommitmentSeriesState	UNKNOWN, ACTIVE, RESTING, RETIRED	UNKNOWN represents the Solidity None sentinel and unexpected values.
shared	shared	packages/shared/src/modules/commitment-pooling/types-vocabulary.ts · CommitmentSeriesState	UNKNOWN, ACTIVE, RESTING, RETIRED

Specified vocabularies without an implemented source

These vocabularies are canonical specifications whose declared implementation anchor has not arrived. The gate watches each anchor and requires the source status and representations to be updated when it lands.

EAS Schemas

assessment — Green Goods Assessment v2

source: implemented · revocable: false · resolver: packages/contracts/src/resolvers/Assessment.sol

Field	Type
title	string
description	string
assessmentConfigCID	string
domain	uint8
startDate	uint256
endDate	uint256
location	string

work — Green Goods Work Submission

source: implemented · revocable: false · resolver: packages/contracts/src/resolvers/Work.sol

Field	Type
actionUID	uint256
title	string
feedback	string
metadata	string
media	string[]

workApproval — Green Goods Work Approval

source: implemented · revocable: false · resolver: packages/contracts/src/resolvers/WorkApproval.sol

Field	Type
actionUID	uint256
workUID	bytes32
approved	bool
feedback	string
confidence	uint8
verificationMethod	uint8
reviewNotesCID	string

badge — GreenGoodsBadge

source: implemented · revocable: true · resolver: none

Registered via the standalone badge-schemas path outside config/schemas.json; the only revocable Green Goods schema, with no resolver. Records no canonical entity: GreenWill badging is a demonstration sidecar, not part of the v1 entity set.

Field	Type
badgeType	string
recipient	address
earnedAt	uint40
evidenceUri	string
tier	uint8

assessmentV3 — Green Goods Assessment v3

source: implemented · revocable: false · resolver: none

Assessment v2 fields plus assessmentKind, cycleId, and baselineUID; one of exactly two new EAS registrations in the commitment-pooling track.

Field	Type
title	string
description	string
assessmentConfigCID	string
domain	uint8
startDate	uint256
endDate	uint256
location	string
assessmentKind	uint8
cycleId	uint256
baselineUID	bytes32

communityTestimony — Green Goods Community Testimony

source: implemented · revocable: false · resolver: none

Community-Hat-gated testimony attached to a commitment; the second of exactly two new EAS registrations. Records no canonical entity yet: community testimony is specified but has no entity until the surface is designed.

Field	Type
commitmentId	uint256
title	string
testimonyCID	string

need — Green Goods Need

source: specified · revocable: true · planned resolver: NeedsResolver

Root Needs use EAS recipient as the canonical garden, refUID zero, and expirationTime zero. NeedsResolver authorizes the attester through the recipient garden's Community role.

Field	Type
statementCID	string
desiredOutcomeCID	string
horizon	uint8
mediaCID	string

needSignal — Green Goods Need Signal

source: specified · revocable: true · planned resolver: NeedsResolver

Child signal records use EAS recipient as the garden, refUID as the exact live same-garden Need, and expirationTime zero. Readers derive one current direction per attester through the canonical latest-winner rule.

Field	Type
support	bool

needStatus — Green Goods Need Status

source: specified · revocable: false · planned resolver: NeedsResolver

Steward-authored child moderation records use EAS recipient as the garden, refUID as the exact live same-garden Need, and expirationTime zero. mergedIntoNeedUID remains custom data because it is a second Need relationship.

Field	Type
status	uint8
domains	uint8[]
mergedIntoNeedUID	bytes32
noteCID	string

fundingAttribution — Green Goods Funding Attribution

source: specified · revocable: false · planned resolver: FundingAttributionResolver

Ungated child funding records use EAS recipient as the garden, refUID as the exact live same-garden Need, and expirationTime zero. FundingAttributionResolver remains separate from NeedsResolver and the joined reader verifies canonical receipts before display.

Field	Type
chainId	uint256
txHash	bytes32
token	address
amount	uint256
rail	uint8

Constraints

Cross-layer invariants and where they are enforced. This catalog is documentation-grade: the drift gate verifies the anchors exist, not the semantics — the contracts and their tests own the semantics.

• domain-closed-set · closed-set · implemented — Action domains form a closed four-member set; resolvers reject domain values above 3 and garden domain masks are validated as 4-bit. (enforced at: packages/contracts/src/registries/Action.sol:28-34, packages/contracts/src/resolvers/Assessment.sol:134-136)
• work-attester-role · domain-range · implemented — A Work attestation's attester must be a gardener or steward of the recipient garden, and the referenced action must exist, be started, not be expired, and belong to a domain enabled on that garden. (enforced at: packages/contracts/src/resolvers/Work.sol:87-139)
• approval-steward-only · domain-range · implemented — Only a steward of the garden may attest a Work Approval, and the approval's actionUID and recipient must match the referenced Work attestation. (enforced at: packages/contracts/src/resolvers/WorkApproval.sol:115-177)
• approval-no-self-attestation · disjoint · implemented — The approver and the work attester must be different accounts — self-approval reverts. (enforced at: packages/contracts/src/resolvers/WorkApproval.sol#SelfAttestation)
• assessment-author-role · domain-range · implemented — An Assessment attester must be an evaluator or steward of the recipient garden. (enforced at: packages/contracts/src/resolvers/Assessment.sol:118-122)
• yield-split-sum · sum · implemented — The three-way yield split (CookieJar / Hypercert fractions / Juicebox) must sum to exactly 10000 bps. (enforced at: packages/contracts/src/resolvers/Yield.sol:107,373)
• garden-nft-transfer-restriction · non-transferable · implemented — Garden NFT transfers obey the TransferRestriction mode (Unrestricted / OwnerOnly / Locked); minting is always allowed. (enforced at: packages/contracts/src/tokens/Garden.sol#_beforeTokenTransfer)
• resolver-schema-pinning · existence · implemented — Each core resolver validates that incoming attestations use its pinned schema UID. (enforced at: packages/contracts/src/resolvers/Work.sol:87-95, packages/contracts/src/resolvers/WorkApproval.sol:115-123, packages/contracts/src/resolvers/Assessment.sol:98-106)
  • ⚠️ Hole: Schema validation is skipped while the stored schemaUID is zero (the deployment window) — a documented gap the commitment-pooling spec explicitly refuses to inherit (its module deploys fail-closed). (packages/contracts/src/resolvers/Work.sol:60-62, packages/contracts/src/resolvers/WorkApproval.sol:81-83, packages/contracts/src/resolvers/Assessment.sol:71-73)
• pooling-allocation-bps-sum · sum · implemented — The six-role allocation snapshot stored at cycle open must sum to exactly 10000 bps and is immutable for the cycle. (enforced at: packages/contracts/src/lib/CommitmentPooling/CyclesLib.sol:67-85)
• pooling-provider-confirmation-disjoint · disjoint · implemented — Every member of a commitment's accountable lead/contributor team is excluded from every fulfillment-confirmation path, including the steward fallback; confirmation defaults are direction-aware (Offer → recipient, Request → creator). (enforced at: packages/contracts/src/lib/CommitmentPooling/ConfirmLib.sol:101-195)
• pooling-recognition-allocation-sum · sum · implemented — The gardener-class recognition budget is fully allocated only after every fulfilled commitment has an eligible contributor: equal budget per fulfilled commitment, then the immutable cycle-open RecognitionPolicy allocates its equal-participation and verified-contribution components through separate deterministic remainder passes before the row results are added. The protocol default and immutable cycle-less preset are 20% equal / 80% verified, but an opened cycle may select any two values summing to 10000 bps. Zero eligible contributors block certificate expansion; there is no lead fallback. (enforced at: packages/contracts/src/lib/CommitmentPooling/RecognitionLib.sol:58-147)
• pooling-payout-plan-conservation · sum · implemented — An explicitly finalized commitment payout plan conserves the declared support amount exactly: garden-retained amount plus all contributor child amounts equals the parent amount. A zero-child all-retained plan completes at finalization without a transfer. (enforced at: packages/contracts/src/lib/Settlement/PlanLib.sol:240-289, 562-586)
• pooling-payout-plan-integrity · functional · implemented — Each fulfilled commitment has at most one stable payout-plan pointer. The complete recognition vector matches its snapshot hash, payment weights derive from the atomic amount vector, finalization precedes dispatch, and child or batch cancellation never clears the parent pointer. (enforced at: packages/contracts/src/lib/Settlement/PlanLib.sol:148-200, 240-337, 545-616)
• pooling-one-open-season · functional · implemented — A pool may have at most one open Season at a time (O(1) openSeasonCycleId guard); Campaigns may overlap freely. (enforced at: packages/contracts/src/lib/CommitmentPooling/CyclesLib.sol:73-88, 177-193)
• commitment-register-non-transferable · non-transferable · implemented — CommitmentRegistry unit classes are non-transferable by construction — no transfer, approval, or custody surface; balances move only via the module. (enforced at: packages/contracts/src/registries/Commitment.sol:11-159)
• needs-eas-envelope-reference · domain-range · specified — All four Needs schemas use EAS recipient as the canonical garden and expirationTime zero; a Need is a root with refUID zero, while NeedSignal, NeedStatus, and FundingAttribution use refUID to reference an exact live same-garden Need. (specified in .plans/backlog/community-interface/spec.md; watches packages/contracts/src/resolvers/Needs.sol#NeedsResolver)
• need-signal-latest-winner · functional · specified — For each Need and attester, readers first select the greatest unsigned (timeCreated, uid) NeedSignal tuple and then apply revocation and expiry; a revoked or expired winner clears the signal without restoring an older record, and support and non-support remain separate counts. (specified in .plans/backlog/community-interface/spec.md; watches packages/shared/src/modules/community-needs/signals.ts#NeedSignal)
• needs-resolver-trust-boundaries · closed-set · specified — Exactly four Needs schemas route through two resolvers: NeedsResolver accepts only Need, NeedSignal, and NeedStatus with schema-specific Community or Steward authorization, while the ungated FundingAttribution schema routes through FundingAttributionResolver; unknown schema branches fail closed. (specified in .plans/backlog/community-interface/spec.md; watches packages/contracts/src/resolvers/Needs.sol#NeedsResolver)

State Machines

work-display-status

The union in types/domain.ts documents itself as the single source of truth: pending/approved/rejected reflect protocol state; syncing/uploading/sync_failed/offline are client-derived from the offline job queue.

State	Storage
pending	protocol
approved	protocol
rejected	protocol
syncing	client-derived
uploading	client-derived
sync_failed	client-derived
offline	client-derived

From	To	Layer	Mechanism
offline · sync_failed	syncing	off-chain	the offline job queue starts or retries the Work submission
syncing	uploading	off-chain	queued media begins uploading before the attestation is submitted
syncing · uploading	sync_failed	off-chain	a recoverable queue or upload failure preserves the job for retry
uploading	pending	on-chain	successful EAS Work attestation submission creates the pending public record
pending	approved · rejected	on-chain	a steward records a separate Work Approval attestation

commitment-pool

Every pool state is on-chain; transitions are rare steward-console actions.

State	Storage
None	on-chain
NotReady	on-chain
Ready	on-chain
Open	on-chain
Paused	on-chain
Closed	on-chain
Composted	on-chain

From	To	Layer	Mechanism
None	NotReady	on-chain	onGardenMinted (GardenToken-only, idempotent) or registerPool → PoolRegistered
NotReady	Ready	on-chain	markPoolReady — requires non-empty charter CID and a non-zero provider open-commitment cap → PoolReady
Ready	Open	on-chain	openPool → PoolOpened
Open	Paused	on-chain	pausePool with mandatory reasonCID → PoolPaused; resumePool returns to Open
Open · Paused	Closed	on-chain	closePool → PoolClosed
Closed	Composted	on-chain	compostPool → PoolComposted
Composted	Ready · Open	on-chain	reopenPool(toOpen) → PoolReopened

commitment-cycle

One open Season per pool (openSeasonCycleId guard); Campaigns overlap freely. Succession between cycles is derived by pool ordering — no on-chain predecessor pointer.

State	Storage
None	on-chain
Seeded	on-chain
Open	on-chain
InProgress	derived
Reviewing	derived
Reconciled	on-chain
Composted	on-chain
Cancelled	on-chain

From	To	Layer	Mechanism
None	Seeded	on-chain	seedCycle(poolId, cycleType, startTime, endTime, metadataCID) → CycleSeeded; no allocation stored yet
Seeded	Open	on-chain	openCycle(cycleId, allocation, recognitionPolicy) — six-role allocation bps and two-part recognition bps each sum to 10000, both store immutably → CycleOpened
Open	InProgress	derived	first CommitmentAccepted for the cycle OR block time ≥ startTime
InProgress	Reviewing	derived	block time > endTime, OR all cycle commitments terminal or ReadyForConfirmation; new evidence/work flips back
Reviewing	Reconciled	on-chain	closeCycle (the reconcile act) requires liveCommitmentCount = 0 → CycleClosed; commitment-level Reconciled derives from this event
Reconciled	Composted	on-chain	compostCycle → CycleComposted
Seeded · Open	Cancelled	on-chain	cancelCycle(reasonCID) requires liveCommitmentCount = 0 → CycleCancelled; Draft is discarded off-chain

commitment

Direction-aware fulfillment: the party receiving the team's work confirms by default (Offer → receiver, Request → creator), or a named group may be set before acceptance. A current local-garden steward/owner may use PoolFallback. When explicitly selected before acceptance and no ordinary/local confirmer is reachable, a current steward/owner of the registered Green Goods protocol garden may use ProtocolFallback. The authority paths are not time-based; module ownership alone grants neither fallback; every lead/contributor is excluded. Evidence/Work credit records only while Accepted and unfrozen; the contributor roster and credit ledger freeze atomically on the transition to ReadyForConfirmation or before a direct Fulfilled dispute resolution; Ready requires pre-freeze totalVerifiedCredits > 0 and a structurally reachable confirmer, while recognition additionally requires Fulfilled plus an opened cycle policy or the immutable cycle-less 20/80 default; disputes restore an explicitly stored prior state.

State	Storage
None	on-chain
Offered	on-chain
Requested	on-chain
Accepted	on-chain
Active	derived
EvidenceSubmitted	derived
PartiallyApproved	derived
ReadyForConfirmation	on-chain
Fulfilled	on-chain
Reconciled	derived
Cancelled	on-chain
Expired	on-chain
Disputed	on-chain

From	To	Layer	Mechanism
None	Offered · Requested	on-chain	createCommitment → CommitmentCreated (direction sets the initial state)
Offered · Requested	Accepted	on-chain	claimCommitment (runtime kind must equal immutable claimType; Open mode transitions immediately, ApprovalGated waits for steward acceptClaim) → CommitmentAccepted; register records committed units
Accepted	Active	derived	first WorkLinked or EvidenceAttached after acceptance
Active	EvidenceSubmitted	derived	any EvidenceAttached or WorkLinked event
EvidenceSubmitted	PartiallyApproved	derived	ApprovedWorkCounted with some requirement counters below their required counts
Accepted · Active · EvidenceSubmitted · PartiallyApproved	ReadyForConfirmation	on-chain	automatic once every repeatable action requirement is met and any declared assessment attached; submitForConfirmation for evidence-only types requires evidenceCount ≥ 1; steward markReadyForConfirmation with reason; every path requires an Open cycle when scoped or the immutable cycle-less 20/80 policy, pre-freeze totalVerifiedCredits > 0, and either a reachable ordinary named/default confirmer threshold or an explicitly selected registered protocol-garden fallback; local-garden authority is confirmation-time PoolFallback provenance only and does not independently satisfy Ready reachability; contributor roster and credit ledger freeze atomically before the ready event
ReadyForConfirmation	Fulfilled	on-chain	confirmFulfillment by named confirmer or direction-aware default, or confirmFulfillmentAsFallback with reason by current local-garden authority (PoolFallback) or explicitly selected registered protocol-garden authority (ProtocolFallback); local authority wins for dual-role callers; threshold N → CommitmentFulfilled with actor/path/reason; register converts units; every lead/contributor on the already-frozen roster is excluded from every confirmation path
Fulfilled	Reconciled	derived	CycleClosed for the commitment's cycle (or PoolClosed when cycle-less)
Offered · Requested · Accepted	Cancelled	on-chain	cancelCommitment(reasonCID) — creator or steward pre-acceptance, steward-only after; Accepted releases committed units
Offered · Requested · Accepted · ReadyForConfirmation	Expired	on-chain	expireCommitment — permissionless once past dueDate (or cycle endTime); releases still-committed units
Accepted · ReadyForConfirmation · Expired	Disputed	on-chain	raiseDispute(reasonCID) — module stores the exact prior state in preDisputeState → CommitmentDisputed
Disputed	Accepted · ReadyForConfirmation · Fulfilled · Cancelled · Expired	on-chain	resolveDispute steward-only; RestorePrevious replays preDisputeState; an Expired prior state can never resolve Fulfilled; a direct Fulfilled resolution requires an available recognition policy and verified contributor, then freezes an unfrozen roster before DisputeResolved

commitment-loan

Records-only pool credit (CreditRegistry). Default is not terminal — a defaulted loan can still be repaid, recorded as LoanRepaid(recoveredFromDefault = true). Registry pause blocks every mutation except markDefaulted and cancelLoan (wind-down). The G$ leg binds the loan to exactly one Confirmed DisbursementKind.LoanPrincipal settlement child; nothing in this machine moves value. Drawn as D30 in the commitment-pooling gallery.

Implementation evidence: packages/contracts/src/registries/Credit.sol#requestLoan, packages/contracts/test/unit/CreditRegistry.t.sol#testCreditRegistry_requestApproveDisburseAndRepayInInstallments, packages/indexer/test/credit-registry.test.ts#CreditRegistry.

State	Storage
None	on-chain
Requested	on-chain
Approved	on-chain
Disbursed	on-chain
Repaid	on-chain
Defaulted	on-chain
Cancelled	on-chain
Repaying	derived

From	To	Layer	Mechanism
None	Requested	on-chain	requestLoan(params) → LoanRequested; pool member for self or steward onBehalfOf; pool Open + credit enabled; principal within remaining borrowerCap
Requested	Approved	on-chain	approveLoan(loanId) → LoanApproved; steward, never the borrower (SelfApproval); re-checks authority and reserves cap exposure
Requested	Cancelled	on-chain	cancelLoan(loanId, reasonCID) → LoanCancelled; borrower or steward
Approved	Disbursed	on-chain	recordDisbursed(loanId, rail, executionRef) → LoanDisbursed; steward or pool executor; reservation becomes outstanding; the G$ rail requires the one field-matched Confirmed LoanPrincipal child
Approved	Cancelled	on-chain	cancelLoan(loanId, reasonCID) → LoanCancelled; steward; any settlement child must already be Cancelled; releases the cap reservation
Disbursed	Repaid	on-chain	recordRepayment(loanId, amount, executionRef) clearing principal + fee → RepaymentRecorded + LoanRepaid; steward or executor, never the borrower; Jar/Treasury only
Disbursed	Defaulted	on-chain	markDefaulted(loanId, reasonCID) → LoanDefaulted; steward; past dueDate only (NotDue); callable while paused
Defaulted	Repaid	on-chain	recordRepayment clearing the balance → LoanRepaid(recoveredFromDefault = true); default is not terminal

Agent query seam

Agents and application code should use the compact read-only query API exported by @green-goods/shared. It resolves canonical ids, typed refs, display names, and declared aliases without importing the full semantic sidecar.

import {
  getOntologyMaturity,
  getOntologyRelationships,
  getOntologySafeClaims,
  getOntologyTerm,
} from "@green-goods/shared";

const term = getOntologyTerm("Commitment");
const maturity = getOntologyMaturity("entity:commitment");
const relationships = getOntologyRelationships("Commitment");
const claims = getOntologySafeClaims("Commitment");

Use maturity.availability and the returned evidence before making a release claim. A canonical term can still be planned or deployed without being available to users.

Known Issues

• missing-capital-mapping-fn — No runtime mapping function exists between the numeric Capital enum and the lowercase CapitalType union; index-based bridges are unsafe because the two declared orders currently differ. (packages/shared/src/types/domain.ts, packages/shared/src/types/hypercerts.ts)
• community-surface-token — The ontology uses a community surface token on Need, Commitment, and Commitment Contributor while the product still treats community experiences as part of the client and public surfaces. Either promote Community to a distinct product surface or fold the token into client; until then the generated glossary carries the declared value verbatim. (docs/docs/reference/glossary.generated.mdx, packages/shared/src/ontology/green-goods-ontology.json)

Deliberately excluded from v1

• Impact-axes taxonomy — canon is maintained outside the repo; this public file carries only the four production action domains.
• ModuleDependency and ModuleSchemaKind from the commitment-pooling spec — module wiring plumbing, not domain vocabulary.

How this page stays honest

bun run check --only ontology cross-checks declared representations, evidence paths, stable implementation symbols, state-machine structure, Solidity and GraphQL enums, shared TypeScript vocabularies, EAS schemas, formal definition tables, and public glossary links. Constraint prose and transition behavior remain test-owned rather than inferred by this gate. Known drift stays bidirectional in scripts/data/ontology-drift-baseline.json. To change the ontology, edit its semantic or projection source and run bun run scripts/quality/check-ontology.mjs --generate and bun run scripts/docs/generate.mjs --scope ontology.