docs(world-model): describe what the current schema enables#373
Conversation
Reframes from a project-tracking artifact into a clean architecture description. Drops PR/wave tables and revert archeology; explains how the existing schema (per-org `entities`, `entity_types.id` global FK reference, `organization.visibility`, `$member` + `entity_identities`) supports the world-model story end-to-end. 163 lines, organised: TL;DR → primitives → org topology → cross-org references → identity → templates → contribution flow → tax / agent community use cases → invariants → deferred work.
github-actions
Bot
added
the
triage:needs-human
|
Triage decision: needs-human Reasons:
Next: Manual review and merge required due to size threshold |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4355575609
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - Write-side guard: when inserting an `entity_relationship`, validate that | ||
| the target's org is either the same as the source or has | ||
| `visibility='public'`. The relationship's organization_id always matches |
There was a problem hiding this comment.
This section describes the cross-org write guard as current behavior, but the code path still rejects all cross-org links: validateScopeRule enforces both entities belong to ctx.organizationId and manage_entity always calls it before insert (packages/owletto-backend/src/utils/relationship-validation.ts, packages/owletto-backend/src/tools/admin/manage_entity.ts). The integration test should reject cross-org relationship in multi-tenant mode also codifies this (packages/owletto-backend/src/__tests__/integration/relationships/entity-relationships.test.ts). As written, readers will expect tenant→public edges to work today when they do not.
Useful? React with 👍 / 👎.
| - Lookup of `entity_types` widens at write time via a **schema search path**: | ||
| the agent declares which public catalogs it operates over, and the runtime | ||
| walks [user's tenant org, then each declared catalog] when resolving a | ||
| slug → `entity_type_id`. The resolved id is materialized on the entity row, | ||
| so reads never need the search path. |
There was a problem hiding this comment.
The document now states that write-time entity type lookup walks [tenant org, declared catalogs], but the current writers resolve type slugs only within the current org (WHERE slug = ... AND organization_id = ...) and return unknown-type errors otherwise (packages/owletto-backend/src/utils/entity-management.ts, packages/owletto-backend/src/utils/entity-link-upsert.ts). There is no corresponding uses_catalog-driven lookup in the write path, so this text overstates present functionality and can mislead implementers about cross-org vocabulary support.
Useful? React with 👍 / 👎.
1 participant
Reframes `docs/plans/world-model.md` from a project-tracking artifact into a clean architecture description.
What changed
163 lines, no PR archaeology.
Test plan