docs: add plan to sync SDK up to lexicons beta.13

Author: aspiers

specs/lexicon-sync/v0.10.0-beta.11-v0.10.0-beta.13.md

@@ -0,0 +1,266 @@
+# Lexicon Sync Plan: v0.10.0-beta.11 → v0.10.0-beta.13
+
+This document outlines the step-by-step plan for syncing the SDK with the latest lexicon changes, following on from
+`v0.10.0-beta.4-v0.10.0-beta.11.md`.
+
+Each change must be implemented, validated, and reviewed before proceeding to the next.
+
+## Current Status
+
+- **Old version**: 0.10.0-beta.11
+- **New version**: 0.10.0-beta.13
+- **Dependency updated**: ⏳ Not yet
+- **Build status**: ⏳ Not yet tested
+- **Test status**: ⏳ Not yet tested
+
+## Changes to Implement
+
+### Change 1: Simplify workScope to union of strongRef and string (beta.12)
+
+**CHANGELOG Reference**: PR #125 - Simplify workScope to union of strongRef and string
+
+**What Changed**:
+
+- The `workScope` field in `org.hypercerts.claim.activity` is now a union of:
+  - `com.atproto.repo.strongRef`: A reference to a work-scope logic record for structured, nested work scope definitions
+  - `org.hypercerts.claim.activity#workScopeString`: A free-form string for simple or legacy scopes
+- **Removed** from `org.hypercerts.defs`:
+  - `workScopeAll` (logical AND operator)
+  - `workScopeAny` (logical OR operator)
+  - `workScopeNot` (logical NOT operator)
+  - `workScopeAtom` (atomic scope reference)
+
+This simplification allows work scope complexity to be managed via referenced records while still supporting simple
+string-based scopes for straightforward use cases.
+
+**SDK Tasks**:
+
+- [ ] Remove type exports that were added for work scope expression types:
+  - Remove `HypercertWorkScopeAll` type (if it exists)
+  - Remove `HypercertWorkScopeAny` type (if it exists)
+  - Remove `HypercertWorkScopeNot` type (if it exists)
+  - Remove `HypercertWorkScopeAtom` type (if it exists)
+  - Remove `HypercertWorkScopeExpression` union type (if it exists)
+- [ ] Remove type exports for work scope tag (if they exist):
+  - Remove `CreateWorkScopeTagParams` (if it exists)
+  - Remove `UpdateWorkScopeTagParams` (if it exists)
+  - Remove `WorkScopeTagParams` (if it exists)
+- [ ] Verify `CreateHypercertParams.workScope` supports the new union type (string | StrongRef)
+- [ ] Update documentation about work scope to reflect the simplified approach
+- [ ] Update usage examples to show:
+  - Simple string-based work scope
+  - StrongRef to a work scope logic record
+- [ ] Update/remove tests for work scope expressions (they should now reference external records)
+- [ ] Build and test
+- [ ] Create changeset (major - breaking change, removed types)
+
+**Validation**:
+
+- [ ] Format check passes (`pnpm format:check`)
+- [ ] Lint passes (`pnpm lint`)
+- [ ] Typecheck passes (`pnpm typecheck`)
+- [ ] Build passes (`pnpm build`)
+- [ ] Tests pass (`pnpm test`)
+- [ ] Types export correctly
+- [ ] Work scope types are correct (string | StrongRef)
+
+**Status**: ⏳ Pending
+
+---
+
+### Change 2: Refactor measurement lexicon schema (beta.12)
+
+**CHANGELOG Reference**: PR #120 - Refactor measurement lexicon schema: add unit field, date ranges, and locations array
+
+**What Changed**:
+
+- Changed required fields: removed `measurers` from required, added `unit` as required
+- Added `unit` field (required, string, maxLength: 50): The unit of the measured value (e.g. kg CO₂e, hectares, %, index
+  score)
+- Added `startDate` field (optional, datetime): The start date and time when the measurement began
+- Added `endDate` field (optional, datetime): The end date and time when the measurement ended
+- Changed `location` (single strongRef) to `locations` (array of strongRefs, maxLength: 100)
+- Moved `measurers` from required to optional field
+- Added `comment` field (optional, string): Short comment suitable for previews and list views
+- Added `commentFacets` field (optional, array): Rich text annotations for `comment` (mentions, URLs, hashtags, etc.)
+- Updated field descriptions for `metric` and `value` with more detailed examples
+
+**SDK Tasks**:
+
+- [ ] Update `CreateMeasurementParams` type to reflect:
+  - `unit` is now required
+  - `measurers` is now optional
+  - `location` renamed to `locations` (array of StrongRef/LocationParams)
+  - Add `startDate` (optional datetime)
+  - Add `endDate` (optional datetime)
+  - Add `comment` (optional string)
+  - Add `commentFacets` (optional array of RichTextFacet)
+- [ ] Update `UpdateMeasurementParams` accordingly
+- [ ] Update `createMeasurement()` method to handle new required `unit` field
+- [ ] Update `createMeasurement()` and `updateMeasurement()` methods to handle `locations` array
+- [ ] Add JSDoc documentation about the new fields (unit, startDate, endDate, comment, commentFacets)
+- [ ] Add usage examples showing:
+  - Creating measurements with unit (required)
+  - Adding date ranges (startDate/endDate)
+  - Using locations array
+  - Adding comments with facets
+- [ ] Add/update tests for measurements with new fields
+- [ ] Build and test
+- [ ] Create changeset (major - breaking change, required field added, location → locations)
+
+**Validation**:
+
+- [ ] Format check passes (`pnpm format:check`)
+- [ ] Lint passes (`pnpm lint`)
+- [ ] Typecheck passes (`pnpm typecheck`)
+- [ ] Build passes (`pnpm build`)
+- [ ] Tests pass (`pnpm test`)
+- [ ] Types export correctly
+
+**Status**: ⏳ Pending
+
+---
+
+### Change 3: Rename evidence lexicon to attachment (beta.13)
+
+**CHANGELOG Reference**: PR #118 - Rename evidence lexicon to attachment and refactor schema structure
+
+**What Changed**:
+
+- **Lexicon ID change:**
+  - `org.hypercerts.claim.evidence` → `org.hypercerts.claim.attachment`
+- **Schema structure changes (`org.hypercerts.claim.attachment`):**
+  - Changed `subject` (single strongRef) to `subjects` (array of strongRefs, maxLength: 100)
+  - Changed `content` from single union (uri/blob) to array of unions (maxLength: 100)
+  - Added `contentType` field (string, maxLength: 64) to specify attachment type
+  - Added `location` field (optional strongRef) to associate location metadata
+  - Removed `relationType` field (previously used to indicate supports/challenges/clarifies)
+  - Removed `contributors` field
+  - Removed `locations` field
+  - Added rich text support: `shortDescriptionFacets` and `descriptionFacets` (arrays of `app.bsky.richtext.facet`)
+  - Updated required fields: `["title", "content", "createdAt"]` (content is now required)
+- **Common definitions (`org.hypercerts.defs`):**
+  - Added `weightedContributor` def for contributor references with optional weights
+  - Added `contributorIdentity` def for string-based contributor identification
+
+**SDK Tasks**:
+
+- [ ] Rename all SDK references from "evidence" to "attachment":
+  - Type exports: `HypercertEvidence` → `HypercertAttachment`
+  - Type exports: `CreateEvidenceParams` → `CreateAttachmentParams`
+  - Type exports: `UpdateEvidenceParams` → `UpdateAttachmentParams`
+  - Type exports: `EvidenceParams` → `AttachmentParams`
+  - Interface methods (if they exist): `createEvidence` → `createAttachment`
+  - Interface methods (if they exist): `updateEvidence` → `updateAttachment`
+  - Interface methods (if they exist): `deleteEvidence` → `deleteAttachment`
+  - Interface methods (if they exist): `listEvidence` → `listAttachments`
+- [ ] Update `CreateAttachmentParams` type to reflect:
+  - `subject` → `subjects` (array of StrongRef/ActivityParams/CollectionParams)
+  - `content` is now array of unions (uri/blob) and required
+  - Add `contentType` (optional string)
+  - Add `location` (optional StrongRef/LocationParams)
+  - Remove `relationType`
+  - Remove `contributors`
+  - Remove `locations` (note: there's a new singular `location` field)
+  - Add `shortDescriptionFacets` (optional array)
+  - Add `descriptionFacets` (optional array)
+- [ ] Update `UpdateAttachmentParams` accordingly
+- [ ] Add type exports for new common definitions:
+  - `HypercertWeightedContributor` = `OrgHypercertsDefs.WeightedContributor`
+  - `HypercertContributorIdentity` = `OrgHypercertsDefs.ContributorIdentity`
+- [ ] Update CRUD methods to handle schema changes
+- [ ] Add JSDoc documentation about attachment fields and migration from evidence
+- [ ] Add usage examples showing:
+  - Creating attachments with subjects array
+  - Using content array with contentType
+  - Adding location to attachments
+  - Using weighted contributors
+- [ ] Add/update tests for attachments
+- [ ] Build and test
+- [ ] Create changeset (major - breaking change, renamed lexicon and schema changes)
+
+**Validation**:
+
+- [ ] Format check passes (`pnpm format:check`)
+- [ ] Lint passes (`pnpm lint`)
+- [ ] Typecheck passes (`pnpm typecheck`)
+- [ ] Build passes (`pnpm build`)
+- [ ] Tests pass (`pnpm test`)
+- [ ] Types export correctly
+
+**Status**: ⏳ Pending
+
+---
+
+### Change 4: Add inline string format to app.certified.location (beta.13)
+
+**CHANGELOG Reference**: PR #131 - Add inline string format to app.certified.location schema with documentation and
+examples
+
+**What Changed**:
+
+- `app.certified.location` now supports inline string format in addition to the structured object format
+- This allows locations to be specified as simple strings for convenience
+
+**SDK Tasks**:
+
+- [ ] Verify `CreateLocationParams` supports both string and structured object format
+- [ ] Update `createLocation()` method to handle string format
+- [ ] Update documentation to show both formats:
+  - Simple string format: `"New York, NY, USA"`
+  - Structured object format: `{ country: "USA", city: "New York", ... }`
+- [ ] Add usage examples for both formats
+- [ ] Add tests for location string format
+- [ ] Build and test
+- [ ] Create changeset (minor - new feature, backward compatible)
+
+**Validation**:
+
+- [ ] Format check passes (`pnpm format:check`)
+- [ ] Lint passes (`pnpm lint`)
+- [ ] Typecheck passes (`pnpm typecheck`)
+- [ ] Build passes (`pnpm build`)
+- [ ] Tests pass (`pnpm test`)
+- [ ] Types export correctly
+
+**Status**: ⏳ Pending
+
+---
+
+### Change 5: Update dependency and final validation
+
+**Tasks**:
+
+- [ ] Update `@hypercerts-org/lexicon` dependency from `0.10.0-beta.11` to `0.10.0-beta.13` in
+      `packages/sdk-core/package.json`
+- [ ] Run `pnpm install` to update the dependency
+- [ ] Review all individual changesets created in steps 1-4
+- [ ] Consider whether they should be combined into a single changeset or kept separate
+- [ ] Update any top-level documentation if needed
+- [ ] Final build and test of entire SDK
+- [ ] Prepare summary of all changes for user review
+
+**Validation**:
+
+- [ ] Format check passes (`pnpm format:check`)
+- [ ] Lint passes (`pnpm lint`)
+- [ ] Typecheck passes (`pnpm typecheck`)
+- [ ] All builds pass (`pnpm build` - sdk-core and sdk-react)
+- [ ] All tests pass (`pnpm test`)
+- [ ] Changesets are properly formatted
+- [ ] Documentation is complete
+
+**Status**: ⏳ Pending
+
+---
+
+## Notes
+
+- **Breaking changes**: This sync includes several major breaking changes:
+  1. WorkScope simplified to union of string | StrongRef (removes complex expression types)
+  2. Measurement `unit` field now required, `location` → `locations` array
+  3. Evidence lexicon renamed to Attachment with schema changes
+- Each change will be implemented, validated, and reviewed before proceeding to the next
+- The evidence → attachment rename is particularly significant and will require careful migration
+- Work scope simplification reverses the complexity added in beta.8, so we may need to remove code that was added in the
+  previous sync