Entity

​

For

An entity has a name, a description, a type from a published Shape, properties and a revision number. Each change gives the entity a new revision. A deleted entity keeps its history, and you can restore it.

​

Use when

• You look up an entity by name or by id.
• You change the name, description or properties of one entity.
• You delete one entity, or bring a deleted entity back.

​

Not this

• Several new or changed entities in one reviewed step: use a workspace (card workspace).
• A relationship between two entities: use card Relationship.
• A document with text people edit: use card Document.

​

Rules

1. entity.1 Change an entity at the revision you read. Pass it to penumbra graph update as --revision. Enforced when you ask: an entity that moved on is refused. The MCP tool update_node answers revision_conflict. Without --revision, the CLI reads the entity at that moment and uses that revision. A change made between your own read and that call is then not caught.
2. entity.2 A direct update replaces the whole property map, and a workspace patch merges into it. penumbra graph update and the MCP tool update_node remove every property you leave out. A patch staged with penumbra graph workspace modify keeps the properties you leave out. Your job: in a direct update, send every property you want to keep. A new item that you staged in the workspace has no earlier map, so an edit of its properties replaces the whole map.
3. entity.3 Deleting is soft. penumbra graph delete deletes the entity and the relationships that touch it. The entity keeps its history. penumbra graph restore brings back the entity only. Your job: restore the relationships yourself. Find a deleted entity by id, not by name.
4. entity.4 A delete waits for approval when an API key or a connected agent makes it. Enforced: the result is pending with an approval URL. A restore does not wait. A workspace that deletes entities waits as well, as rule workspace.10 and card Approval say.
5. entity.5 Properties must fit the entity’s type in its Shape. Enforced: validate and submit report an error diagnostic, such as schema_validation_failed, and apply nothing. Your job: read the type in its Shape with penumbra shapes show before you stage properties.
6. entity.6 A citation belongs to the revision where it was written. Your job: when you edit a checked-out entity, cite the passage that supports the new value. The citations on the old revision are history. They are not copied forward as support for your edit (card Passage and citation).

​

Failure signs

• An update is refused with version_conflict or revision_conflict: read the entity again with penumbra graph get <id>, then change it at the new revision (rule entity.1).
• A delete returns pending: problem change-waits-for-approval.
• A restored entity has no relationships: rule entity.3.

​

Doors

The Kit levels read, propose, confirm and apply do not include update_node, delete_node or restore_node. A Kit at those levels changes entities through a workspace.

​

The CLI word

The CLI calls an entity a node in penumbra graph nodes and penumbra graph traverse. The CLI calls an entity a record and a citation a quote in penumbra evidence list.

​

HTTP reference

• List graph nodes
• Get graph node
• Get node history
• List graph edges
• Get graph edge
• Get edge history
• Count graph records
• Traverse graph
• List graph commits
• Get graph commit

​

Keep going

Workspace · Relationship · Approval · Shape · Passage and citation