Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Canonical Property Target Entity Types
Status
Implementation plan. No code or schema changes have been made as part of this document.
Problem
Tasks are documents with document_sub_type = TASK in the canonical entity and access-control systems, but the properties subsystem currently exposes a separate TASK target type.
That creates two property namespaces for the same entity id:
(DOCUMENT, <document-id>)
(TASK, <document-id>)
Today a task property mutation from the web client sends entityType: TASK, so the properties service writes the assignment under the internal TASK namespace. A fresh GraphQL Soup query represents the same task as a GraphqlSoupDocument, mints document access, and currently loads properties under DOCUMENT. The mutation response is therefore correct and can update the normalized cache immediately, but a fresh read cannot find the row written under TASK.
The split is visible in crates/properties/src/domain/model.rs:
access_entity_type(EntityType::Task)collapses toentity_access::EntityType::Document.PropertiesAccessReceiptthen preserves the original propertiesEntityType::Taskspecifically so repositories can continue using the separate storage namespace.
The desired boundary is:
external target: DOCUMENT + entity id
|
v
inbound adapter mints EntityAccessReceipt<Document>
|
v
properties domain resolves document subtype
|
+-- regular document/snippet -> internal DOCUMENT
`-- task -> internal TASK
TASK remains an internal properties storage type for now. There is no data migration in this plan.
Decisions
- Entity property targets use canonical entity types externally. A task is targeted as
DOCUMENT; task-ness comes from document subtype. - The properties domain receives regular typed entity-access receipts. Clients never provide receipts; inbound adapters mint them.
- Task/document classification is domain policy. Inbound GraphQL, REST, and tool adapters must not inspect document subtype or choose the internal storage namespace.
- Document subtype lookup is an outbound fact. Add a repository/port capability that can resolve document subtypes in batches; the domain maps those facts to internal
models_properties::EntityType::{Document, Task}. - Keep
models_properties::EntityType::Taskinternally. Existing rows, task initialization, task relationships, grouping, indexing, notifications, and permission side effects continue using it. - Separate target types from referenced-entity types. The current
GraphqlPropertyEntityType/generatedEntityTypeis used both for the entity receiving a property and for entities stored inside property values. Introduce a target-only transport type withoutTASK. Keep the existing internal/reference type in this iteration so Parent Task/Subtasks and property-definition constraints are not redesigned accidentally. - Use one resolution path for reads and writes. Fixing only
set_entity_propertywould recreate the mismatch in the opposite direction. - Do not add
Tasktomodel_entity::EntityType. Tasks remain canonical documents. - Do not run or create a database migration for this work. Existing
TASKrows remain authoritative for task documents. - Prefer strong domain types over stringly typed interfaces. Repository and service contracts should use types such as
Uuidfor UUID-backed identifiers rather thanString, converting only at transport boundaries when necessary.
Goals
- A frontend task property write sends
DOCUMENT, notTASK. - GraphQL, REST, tools, and internal user-facing property entrypoints mint a normal document access receipt.
- The properties domain resolves a task document to the internal
TASKnamespace before every repository operation. - A mutation followed by a fresh, network-only GraphQL Soup query returns the persisted assignee/status/etc.
- Task assignee permission grants and notifications continue to run.
- Existing task property rows require no rewrite.
- Bulk property reads classify documents in one batched lookup rather than introducing an N+1 query.
Non-goals
- Removing
TASKfrom PostgreSQL'sproperty_entity_typeenum. - Migrating existing
TASKproperty rows toDOCUMENT. - Changing how tasks are rendered (
TaskEntityremains a document withsubType.type === "task"). - Redesigning task-to-task entity-reference values or Parent Task/Subtasks in the first iteration.
- Changing GraphQL normalized-cache identity.
GraphqlProperty.idremains the assignment id, and tasks remainGraphqlSoupDocumentobjects.
Proposed domain design
1. Canonical target receipt
Replace the original-type-preserving role of PropertiesAccessReceipt<T> for entity-scoped service operations with the regular:
EntityAccessReceipt<ViewAccessLevel>
EntityAccessReceipt<EditAccessLevel>
The receipt's entity type is canonical (Document, EmailThread, Call, CrmCompany, etc.). It proves authorization but does not encode the properties storage namespace.
If removing PropertiesAccessReceipt in one change is too disruptive, first reduce it to a transparent supported-target wrapper around EntityAccessReceipt<T> with no caller-provided properties EntityType. Do not let callers supply or preserve Task on the wrapper. The end-state service contract must not require a caller to choose Task versus Document.
2. Resolved internal subject
Add a private/domain model such as:
struct ResolvedPropertySubject {
canonical_entity: model_entity::OwnedEntity,
storage_entity_type: models_properties::EntityType,
}
The service resolves receipts as follows:
| Receipt entity type | Internal properties type |
|---|---|
Document with task subtype |
Task |
Document without task subtype (including snippets) |
Document |
EmailThread |
Thread |
Call |
CallRecord |
CrmCompany |
Company |
Chat, Channel, Project, User |
corresponding internal type |
| unsupported canonical types | domain validation error |
Keep both the canonical key and internal key while processing a request. The canonical key is used at service/adapter boundaries; only repository calls and task-specific domain behavior use the internal key.
3. Batched document subtype lookup
Extend the properties outbound port with a fact-oriented, batch API, for example:
fn get_document_sub_types(
&self,
document_ids: &[Uuid],
) -> impl Future<
Output = Result<HashMap<Uuid, Option<DocumentSubType>>, Self::Err>
> + Send;
Implementation requirements:
- Keep UUID-backed identifiers strongly typed as
Uuidthroughout domain and repository interfaces; do not weaken them toStringfor convenience. - Query
Document/document_sub_typefor all supplied document ids in one SQLx query. - Return
Some(Task)only for task documents;Nonemeans a regular document/no subtype. Snippets resolve to internalDocument. - Deduplicate input ids.
- Define and test missing-document behavior. Recommended compatibility behavior is to resolve a missing subtype row as
Document; authorization and the eventual repository operation remain responsible for their existing not-found/deleted behavior. - Use SQLx compile-time checked macros.
- Do not put the Task-versus-Document policy in the SQL adapter; return subtype facts and map them in the domain service.
The existing properties repository already contains document metadata lookup, so this capability may live on PropertiesRepo without adding another service generic. If a dedicated resolver port is introduced instead, wire it only in composition roots and keep the domain independent of its concrete database implementation.
4. Canonical bulk result keys
get_bulk_entity_properties currently returns maps keyed by EntityPropertiesKey, whose type can be internal Task. That prevents a caller holding only a canonical Document receipt from finding the result.
Change the service boundary to return canonical keys. Options, in preferred order:
- A map keyed by a new canonical
PropertyTargetKeycontainingmodel_entity::EntityTypeand id. - A map keyed by
model_entity::OwnedEntity. - A vector aligned with the input receipts, if that is clearer for all callers.
Keep EntityPropertiesKey with models_properties::EntityType::Task inside the repository boundary. During bulk reads, retain a canonical-to-internal mapping, query with internal keys, then map results back to canonical keys before returning.
Transport contracts
GraphQL
Create a target-only GraphQL enum, e.g. GraphqlPropertyTargetEntityType, which excludes TASK and maps to canonical entity-access types. Use it only for SetEntityPropertyInput.entity_type and any other entity-scoped property target input.
Do not reuse or remove GraphqlPropertyEntityType yet; it is also used for:
GraphqlEntityReferenceInput.entity_typeGraphqlProperty.specific_entity_type- property filter inputs
Those uses may still need a Task value and are outside this plan's first iteration.
Change the GraphQL mutation flow to:
- Parse canonical target type and entity id.
- Mint
EntityAccessReceipt<EditAccessLevel>at the inbound boundary. - Pass the receipt, definition id, and value to
PropertiesService::set_entity_property. - Let the service resolve internal Task/Document storage type.
Change the GraphQL property reader similarly:
- Keep
GraphqlSoupDocument/model_entity::EntityType::Documentfor tasks. - Mint canonical view receipts.
- Call the bulk properties service.
- Consume results under canonical Document keys.
Do not add task-subtype branching to graphql_soup, complete_graph::SoupEdges, or graphql_properties; that decision belongs in the properties domain.
Likely files:
crates/graphql_properties/src/mutations.rscrates/graphql_properties/src/loaders.rscrates/graphql_common/src/property_filter.rs(only if types must be split/exported here)crates/complete_graph/src/edges.rscrates/complete_graph/src/schema.rsservices/document_storage_service/src/api/graphql_soup.rsstatic_assets/schema.graphql(generated, never edited manually)
REST/OpenAPI
The REST path currently uses the same properties EntityType that includes TASK. Introduce a target-only API type without Task for entity-scoped paths and bulk subject references. Convert it to canonical entity-access types in the receipt extractor.
Keep value-level EntityReference.entity_type separate so this change does not silently alter Parent Task/Subtasks or constrained property definitions.
Likely files:
crates/models_properties/src/api/**crates/properties/src/inbound/axum_router/extract.rscrates/properties/src/inbound/axum_router/entities.rscrates/properties_service/**and DSS OpenAPI composition as required
Tools and internal adapters
Update user-facing tools to target tasks as documents and pass canonical receipts. Internal task lifecycle ports may continue using internal Task rows where they bypass the user-facing target contract deliberately.
Review at least:
crates/properties/src/inbound/toolset/get_entity_properties.rscrates/properties/src/inbound/toolset/set_entity_property.rscrates/ai_tools/src/tool_context.rsservices/document_storage_service/src/api/context.rscrates/documents/src/domain/ports/mod.rscrates/documents/src/domain/service.rs
Do not blindly replace every Task occurrence: task relationship values, filters, system-property initialization, and internal repository keys remain Task in this phase.
Properties service changes
Add one internal resolution helper and use it consistently before repository access. Audit every method that currently reads access.entity_type() or constructs EntityReference/EntityPropertiesKey from a receipt, including:
get_entity_propertiesget_property_value/get_system_property_valueset_entity_propertyadd_entity_property_optionremove_entity_property_optionget_entity_properties_with_definitionsget_entity_metadata_propertiesget_bulk_entity_propertiesdelete_entity_properties- assignment deletion authorization comparisons
- search reindex dispatch after writes
Task-only behavior must use the resolved internal type:
- assignee permission grants
- task-assigned notifications
- Parent Task/Subtasks relationship writes
- task-specific validation
- search indexing as a task
Authorization comparisons must use canonicalized types. For example, an assignment lookup returning internal Task belongs to a receipt for canonical Document; comparing those enums directly would incorrectly reject access.
Likely files:
crates/properties/src/domain/model.rscrates/properties/src/domain/service.rscrates/properties/src/domain/service_impl/mod.rscrates/properties/src/domain/service_impl/task_properties.rscrates/properties/src/domain/ports.rscrates/properties/src/outbound/metadata_queries.rscrates/properties/src/outbound/properties_pg_repo.rscrates/properties/src/domain/test.rscrates/properties/src/outbound/test.rsand focused query tests
Frontend changes
After backend schema/OpenAPI changes and code generation, make property targets canonical:
TaskEntityremains{ type: "document", subType: { type: "task" } }.macroEntityToPropertyEntityType(or its replacement target helper) returnsDOCUMENTfor a task.- Task grid, inline task properties, side panel, row tags, inbox property editors, title/editor property calls, and hotkey bulk property edits pass
DOCUMENTas the target. graphql-properties.tsmaps the new target type and no longer sendsTASKforSetEntityPropertyInput.- Entity-reference conversion remains separate and may still emit
TASKwhere the value schema requires it. - Do not manually edit generated TypeScript.
Audit the hardcoded target call sites found by searching for EntityType.TASK, 'TASK', and isTaskEntity, especially:
apps/web/src/features/property/utils/entityConversion.tsapps/web/src/features/entity/extractors-property/entity-key-properties.tsxapps/web/src/features/next-soup/soup-view/views/tasks/task-grid-layout.tsxapps/web/src/features/next-soup/soup-view/views/inbox/inbox-card-layouts.tsxapps/web/src/features/block-md/component/InlineTaskProperties.tsxapps/web/src/features/block-md/component/sidepanel/MarkdownSidePanelSections.tsxapps/web/src/features/entity/composed/list-entity/wide-layout.tsxapps/web/src/lib/service-clients/service-storage/graphql-properties.ts
Classify each occurrence as either:
- target type: change to canonical
DOCUMENT; or - reference/filter/rendering/internal task classification: retain Task semantics.
Compatibility and atomic rollout
This work uses an atomic deployment strategy. Removing TASK from the GraphQL target input enum is a breaking contract, so the backend and every client must deploy together.
Create the target-only enum without TASK immediately, regenerate all clients in the same change, and deploy the backend and clients atomically. Do not add a deprecated TASK alias or a compatibility phase.
This input-only GraphQL change does not alter normalized record identity or field storage shape, so it does not require a normalized-cache schema compatibility epoch bump. Persisted records may remain in place.
Test plan
Properties domain tests
Add focused tests proving:
- A canonical Document edit receipt for a task resolves to internal
EntityType::Taskfor writes. - A canonical Document view receipt for a task resolves to internal Task for reads.
- A regular document and snippet resolve to internal Document.
- Mixed bulk task/document reads issue one batched subtype lookup and return results under canonical Document keys.
- Assignee updates through a canonical Document receipt still grant permissions and send notifications.
- Parent Task/Subtasks behavior still uses internal Task rows.
- Add/remove option and delete flows resolve the same internal key as set/get.
- Assignment deletion accepts a canonical Document receipt for an assignment stored under Task, but still rejects a receipt for a different entity id.
- Search reindex dispatch retains the resolved internal Task type.
- Missing subtype/document facts follow the documented fallback/error behavior.
Outbound tests
Add query tests for batch subtype resolution:
- task document
- regular document
- snippet
- duplicate ids
- missing id
- mixed batch
Any SQLx query changes require just prepare_db from the repository root. Never edit .sqlx files manually.
GraphQL tests
Add tests proving:
SetEntityPropertyInputaccepts canonicalDOCUMENTfor a task target.- The target-only enum does not expose Task.
- Entity-reference values can still represent the existing Task reference type where required.
- A mutation setting Assignees followed by a fresh/network-equivalent GraphQL Soup query returns the assignee.
- A regular document with the same shape still reads Document-scoped properties.
- The committed SDL matches generated schema.
The key regression test is a mutation-then-fresh-query test; an optimistic-cache-only assertion is not sufficient.
Frontend tests
Add or update tests proving:
- Task property targets are sent as
DOCUMENT. - Regular document targets remain
DOCUMENT. - The assignee mutation still sends
multiEntityReferencevalues correctly. - Task references used as property values are not accidentally converted unless that contract is intentionally changed.
- A real mutation response and subsequent network query keep the task's property linked in the normalized graph.
Generated artifacts
After changing the GraphQL schema:
cargo run -p complete_graph --bin graphql_schema -- static_assets/schema.graphql
(\cd apps/web && bun gen-graphql)
After changing REST/OpenAPI types:
(\cd apps/web && bun gen-api properties-service)
Use the appropriate DSS/cloud-storage target too if its generated OpenAPI exposes the affected routes. Never manually edit generated Rust/TypeScript schema artifacts.
Validation sequence
Run focused validation before workspace-wide checks:
cargo test -p properties
cargo test -p graphql_properties
cargo test -p complete_graph
cargo test -p document_storage_service
just prepare_db # required if SQLx queries changed
(\cd apps/web && bunx vitest run <focused-test-files>)
(\cd apps/web && bun type-check)
Then run the repository Rust validation sequence from the root:
just check
just clippy
just format
Also verify generated contracts are clean/up to date and run git diff --check (or the repository equivalent). Follow the repository rule to create a jj revision after each successful verification checkpoint.
Do not run migrations for this plan; none are expected.
Acceptance criteria
- Web task property mutations send a canonical
DOCUMENTtarget. - No user-facing property target API requires callers to distinguish Task from Document.
- Existing task property rows remain stored and retrieved under internal
TASK. - Both single and bulk property reads resolve task subtype inside the properties domain.
- A successful Assignees mutation remains present after a hard reload/fresh GraphQL Soup network response.
- Assignee permissions and notifications still occur.
- Regular document properties are unaffected.
- No N+1 subtype queries are introduced.
- GraphQL SDL, OpenAPI clients, SQLx metadata, and tests are updated through generators.
Hexagonal architecture boundary
This design keeps dependencies pointing inward:
- Inbound adapters parse canonical target ids/types, authenticate, mint typed entity-access receipts, and call the service. They do not decide whether a document is a task.
- Properties domain service owns Task-versus-Document classification policy and task-specific side-effect orchestration.
- Outbound adapter returns document subtype facts and performs internal Task/Document-keyed persistence; it does not choose business behavior.
- Composition roots wire concrete access, repository, notification, permission, and indexing adapters.
Authorization remains represented by EntityAccessReceipt<ViewAccessLevel/EditAccessLevel>. The subtype resolver must never become a substitute for authorization.