Problem
#118 added entity file upload / download CLI verbs (PR #119), but entity file clear from the original proposal was deliberately omitted: no server route exists to detach an attachment from a file field.
Working around it client-side is wrong:
- A
PATCH setting the field to null would orphan the S3 object — the bytes stay in the bucket with no entity reference, invisible to retention/forensics tooling.
- It bypasses the attachment state machine (
pending → uploaded → scanning → available | quarantined | rejected) and the durable audit chain that the file routes write to (forge.file.* events).
The attachment lifecycle is deliberately centralized server-side (see crates/schema-forge-acton/src/routes/files.rs), so detach must be too.
Proposed route
DELETE /schemas/{schema}/entities/{id}/fields/{field}
- Requires
Write access on the schema (same as mint/confirm), audited to the durable chain (forge.file.detached).
- Sets the field to null on the entity.
- Decide and document the object-disposition policy: delete the S3 object, or retain it under its key for forensics (consistent with how quarantined objects are retained in v1) and rely on lifecycle rules. Retention seems more consistent with the existing posture; deletion could be a config or query flag.
required file fields: detach should be refused (409/422) since it would leave the entity invalid.
- Hook surface: consider whether a
before_detach-style event is needed, or whether the existing audit entry suffices for v1.
CLI follow-up
Once the route lands, add schemaforge entity file clear <schema> <id> <field> wrapping it — the CLI scaffolding from PR #119 (ForgeClient, EntityFileCommands) makes that a small addition.
Refs #118, #119.
Problem
#118 added
entity file upload/downloadCLI verbs (PR #119), butentity file clearfrom the original proposal was deliberately omitted: no server route exists to detach an attachment from afilefield.Working around it client-side is wrong:
PATCHsetting the field tonullwould orphan the S3 object — the bytes stay in the bucket with no entity reference, invisible to retention/forensics tooling.pending → uploaded → scanning → available | quarantined | rejected) and the durable audit chain that the file routes write to (forge.file.*events).The attachment lifecycle is deliberately centralized server-side (see
crates/schema-forge-acton/src/routes/files.rs), so detach must be too.Proposed route
DELETE /schemas/{schema}/entities/{id}/fields/{field}Writeaccess on the schema (same as mint/confirm), audited to the durable chain (forge.file.detached).requiredfile fields: detach should be refused (409/422) since it would leave the entity invalid.before_detach-style event is needed, or whether the existing audit entry suffices for v1.CLI follow-up
Once the route lands, add
schemaforge entity file clear <schema> <id> <field>wrapping it — the CLI scaffolding from PR #119 (ForgeClient,EntityFileCommands) makes that a small addition.Refs #118, #119.