315 lines
12 KiB
Plaintext
315 lines
12 KiB
Plaintext
-- allium: 1
|
|
-- bDS Engine-Level Save Side-Effects
|
|
-- Scope: cross-cutting (all waves)
|
|
-- Distilled from: PostEngine.ts, MediaEngine.ts, TemplateEngine.ts,
|
|
-- ScriptEngine.ts, MetaEngine.ts, TagEngine.ts
|
|
|
|
-- When an entity is saved/published/deleted in the engine layer, a chain
|
|
-- of automatic side-effects fires. These are NOT UI-level concerns —
|
|
-- they happen in the backend regardless of which UI triggered them.
|
|
|
|
use "./post.allium" as post
|
|
use "./media.allium" as media
|
|
|
|
-- ─── External surfaces ──────────────────────────────────────
|
|
|
|
-- Engine-level events emitted after backend operations complete.
|
|
-- These are NOT direct user actions — they fire as side-effects
|
|
-- of user operations processed by the engine layer.
|
|
|
|
surface Engine {
|
|
provides: PostCreated(post)
|
|
provides: PostUpdated(post, changes)
|
|
provides: PostPublished(post)
|
|
provides: PostDeleted(post)
|
|
provides: PostChangesDiscarded(post)
|
|
provides: MediaImported(media)
|
|
provides: MediaUpdated(media, changes)
|
|
provides: MediaFileReplaced(media, new_file)
|
|
provides: MediaDeleted(media)
|
|
provides: TemplateCreated(template)
|
|
provides: TemplateUpdated(template, changes)
|
|
provides: TemplatePublished(template)
|
|
provides: TemplateDeleted(template, force)
|
|
provides: TagDeleted(tag)
|
|
provides: TagRenamed(old_name, new_name)
|
|
provides: TagsMerged(source_tags, target_tag)
|
|
provides: ProjectMetadataUpdated(metadata)
|
|
provides: CategoryAdded(name)
|
|
provides: CategoryRemoved(name)
|
|
provides: PublishingPreferencesUpdated(prefs)
|
|
provides: PostTranslationUpserted(translation, source_post)
|
|
provides: MediaTranslationUpserted(translation, media)
|
|
provides: MediaTranslationDeleted(media, language)
|
|
}
|
|
|
|
-- ─── Post operations ─────────────────────────────────────
|
|
|
|
rule CreatePostSideEffects {
|
|
when: PostCreated(post)
|
|
ensures: FTSIndexUpdated(post)
|
|
ensures: EmbeddingUpdated(post)
|
|
-- No file written (draft lives in DB)
|
|
}
|
|
|
|
rule UpdatePostSideEffects {
|
|
when: PostUpdated(post, changes)
|
|
-- If post is published and content/metadata changes:
|
|
-- auto-transition status back to draft
|
|
-- If slug changed and file exists: rename .md file
|
|
-- If templateSlug changed on published post: rewrite .md frontmatter
|
|
ensures: FTSIndexUpdated(post)
|
|
if changes.content:
|
|
ensures: PostLinksUpdated(post)
|
|
-- Parses markdown/HTML links, resolves slugs to post IDs,
|
|
-- replaces outgoing link rows
|
|
ensures: EmbeddingUpdated(post)
|
|
}
|
|
|
|
rule PublishPostSideEffects {
|
|
when: PostPublished(post)
|
|
ensures: PostFileWritten(post)
|
|
-- posts/YYYY/MM/{slug}.md with YAML frontmatter
|
|
if old_file_path != new_file_path:
|
|
ensures: OldPostFileDeleted(old_file_path)
|
|
ensures: post.content = null
|
|
-- Content cleared from DB; lives in filesystem only
|
|
ensures: FTSIndexUpdated(post)
|
|
ensures: PostLinksUpdated(post)
|
|
-- Also publishes all translations:
|
|
for t in post.translations:
|
|
ensures: TranslationFileWritten(t)
|
|
ensures: t.content = null
|
|
ensures: EmbeddingUpdated(post)
|
|
}
|
|
|
|
rule DeletePostSideEffects {
|
|
when: PostDeleted(post)
|
|
if post.file_path != "":
|
|
ensures: PostFileDeleted(post.file_path)
|
|
ensures: PostLinksDeleted(post)
|
|
-- Deletes both source and target link rows
|
|
for media_link in post.linked_media:
|
|
ensures: MediaSidecarUpdated(media_link.media_id)
|
|
-- Removes post from media sidecar's linkedPostIds
|
|
ensures: FTSIndexDeleted(post)
|
|
ensures: EmbeddingRemoved(post)
|
|
}
|
|
|
|
rule DiscardPostChangesSideEffects {
|
|
when: PostChangesDiscarded(post)
|
|
-- Reads published version from file, restores DB metadata,
|
|
-- sets content=null, status=published
|
|
ensures: FTSIndexUpdated(post)
|
|
}
|
|
|
|
-- ─── Media operations ────────────────────────────────────
|
|
|
|
rule ImportMediaSideEffects {
|
|
when: MediaImported(media)
|
|
ensures: MediaFileWritten(media)
|
|
-- media/YYYY/MM/{uuid}.{ext}
|
|
ensures: SidecarFileWritten(media)
|
|
-- {path}.meta with YAML-like metadata
|
|
if media.is_image:
|
|
ensures: ThumbnailsGenerated(media)
|
|
-- small=150px, medium=400px, large=800px, ai=448x448
|
|
-- Asynchronous, emits thumbnailsGenerated on completion
|
|
ensures: FTSIndexUpdated(media)
|
|
}
|
|
|
|
rule UpdateMediaSideEffects {
|
|
when: MediaUpdated(media, changes)
|
|
ensures: SidecarFileRewritten(media)
|
|
-- Preserves fields caller didn't set (linkedPostIds, author)
|
|
ensures: FTSIndexUpdated(media)
|
|
}
|
|
|
|
rule ReplaceMediaFileSideEffects {
|
|
when: MediaFileReplaced(media, new_file)
|
|
-- Copies new file over existing path
|
|
if media.is_image:
|
|
ensures: ThumbnailsRegenerated(media)
|
|
-- Synchronous (awaited), not fire-and-forget
|
|
}
|
|
|
|
rule DeleteMediaSideEffects {
|
|
when: MediaDeleted(media)
|
|
ensures: MediaFileDeleted(media)
|
|
ensures: SidecarFileDeleted(media)
|
|
ensures: ThumbnailsDeleted(media)
|
|
ensures: PostMediaLinksDeleted(media)
|
|
ensures: MediaTranslationsDeleted(media)
|
|
-- Also deletes all translated sidecar files: {path}.{lang}.meta
|
|
ensures: FTSIndexDeleted(media)
|
|
}
|
|
|
|
-- ─── Template operations ─────────────────────────────────
|
|
|
|
rule CreateTemplateSideEffects {
|
|
when: TemplateCreated(template)
|
|
ensures: TemplateFileWritten(template)
|
|
-- templates/{slug}.liquid with YAML frontmatter
|
|
}
|
|
|
|
rule UpdateTemplateSideEffects {
|
|
when: TemplateUpdated(template, changes)
|
|
ensures: template.version = template.version + 1
|
|
-- DB-first update, then filesystem; rollback DB on filesystem failure
|
|
if changes.slug:
|
|
ensures: TemplateFileRenamed(template)
|
|
ensures: CascadeSlugUpdate(template)
|
|
-- Updates posts.templateSlug and tags.postTemplateSlug
|
|
ensures: TemplateFileRewritten(template)
|
|
}
|
|
|
|
rule PublishTemplateSideEffects {
|
|
when: TemplatePublished(template)
|
|
ensures: TemplateFileWritten(template)
|
|
ensures: template.content = null
|
|
-- Content cleared from DB
|
|
}
|
|
|
|
rule DeleteTemplateSideEffects {
|
|
when: TemplateDeleted(template, force)
|
|
if has_references and not force:
|
|
-- Return without deleting, report reference counts
|
|
ensures: nothing
|
|
if force:
|
|
ensures: ReferencingPostsCleared(template)
|
|
ensures: ReferencingTagsCleared(template)
|
|
-- Nulls out templateSlug on posts, postTemplateSlug on tags
|
|
ensures: TemplateFileDeleted(template)
|
|
}
|
|
|
|
-- ─── Script operations ───────────────────────────────────
|
|
|
|
-- Same pattern as templates:
|
|
-- Create: write published script file, insert DB
|
|
-- Update: bump version, rewrite file, update DB
|
|
-- Publish: write file, clear DB content
|
|
-- Delete: delete file, delete DB row
|
|
|
|
-- ─── Tag operations ──────────────────────────────────────
|
|
|
|
rule DeleteTagSideEffects {
|
|
when: TagDeleted(tag)
|
|
-- Background task:
|
|
-- For each post containing this tag:
|
|
-- Remove tag from post's tags array in DB
|
|
-- If published: rewrite .md file (syncPublishedPostFile)
|
|
ensures: TagsJsonWritten()
|
|
-- meta/tags.json updated
|
|
}
|
|
|
|
rule RenameTagSideEffects {
|
|
when: TagRenamed(old_name, new_name)
|
|
-- Background task:
|
|
-- For each post containing old_name:
|
|
-- Replace old_name with new_name in tags array
|
|
-- If published: rewrite .md file
|
|
ensures: TagsJsonWritten()
|
|
}
|
|
|
|
rule MergeTagsSideEffects {
|
|
when: TagsMerged(source_tags, target_tag)
|
|
-- Background task:
|
|
-- For each source tag, for each post containing it:
|
|
-- Replace source with target (dedup), update DB
|
|
-- If published: rewrite .md file
|
|
-- Delete all source tag rows
|
|
ensures: TagsJsonWritten()
|
|
}
|
|
|
|
-- ─── Settings/Metadata operations ────────────────────────
|
|
|
|
rule UpdateProjectMetadataSideEffects {
|
|
when: ProjectMetadataUpdated(metadata)
|
|
ensures: ProjectJsonWritten()
|
|
-- meta/project.json (atomic write)
|
|
ensures: CategoryMetaJsonWritten()
|
|
-- meta/category-meta.json (atomic write)
|
|
}
|
|
|
|
rule AddCategorySideEffects {
|
|
when: CategoryAdded(name)
|
|
ensures: ProjectJsonWritten()
|
|
ensures: CategoryMetaJsonWritten()
|
|
ensures: CategoriesJsonWritten()
|
|
-- meta/categories.json
|
|
}
|
|
|
|
rule RemoveCategorySideEffects {
|
|
when: CategoryRemoved(name)
|
|
ensures: ProjectJsonWritten()
|
|
ensures: CategoryMetaJsonWritten()
|
|
ensures: CategoriesJsonWritten()
|
|
}
|
|
|
|
rule UpdatePublishingPreferencesSideEffects {
|
|
when: PublishingPreferencesUpdated(prefs)
|
|
ensures: PublishingJsonWritten()
|
|
-- meta/publishing.json (atomic write)
|
|
}
|
|
|
|
-- ─── Translation operations ──────────────────────────────
|
|
|
|
rule UpsertPostTranslationSideEffects {
|
|
when: PostTranslationUpserted(translation, source_post)
|
|
-- If source is published and this is a manual edit (not auto-publish):
|
|
-- transition source post to draft (copies content from file to DB)
|
|
if source_post.status = published and translation.is_manual_edit:
|
|
ensures: source_post.status = draft
|
|
ensures: source_post.content = read_file(source_post.file_path)
|
|
-- If both translation and source are published:
|
|
-- write translation file, clear translation content from DB
|
|
if translation.status = published and source_post.status = published:
|
|
ensures: TranslationFileWritten(translation)
|
|
ensures: translation.content = null
|
|
ensures: FTSIndexUpdated(source_post)
|
|
-- FTS includes all translation content for the source post
|
|
}
|
|
|
|
rule UpsertMediaTranslationSideEffects {
|
|
when: MediaTranslationUpserted(translation, media)
|
|
ensures: TranslatedSidecarWritten(media, translation.language)
|
|
-- {path}.{lang}.meta
|
|
}
|
|
|
|
rule DeleteMediaTranslationSideEffects {
|
|
when: MediaTranslationDeleted(media, language)
|
|
ensures: TranslatedSidecarDeleted(media, language)
|
|
}
|
|
|
|
-- ─── CLI/MCP notification sync ───────────────────────────
|
|
|
|
-- When MCP CLI makes mutations, it writes to db_notifications table.
|
|
-- NotificationWatcher polls DB file (chokidar, 100ms debounce):
|
|
-- Reads unseen CLI notifications
|
|
-- Calls engine.invalidate(entityId) if needed
|
|
-- Sends entity:changed IPC event to renderer
|
|
-- Marks rows as seen
|
|
-- Prunes: >1h processed, >24h unprocessed
|
|
|
|
-- ─── Side-effect summary table ───────────────────────────
|
|
|
|
-- Operation | File Write | FTS | Links | Thumbs | Sidecar | Embed | JSON Meta
|
|
-- -------------------|--------------|------|-------|--------|---------|-------|----------
|
|
-- createPost | no (draft) | yes | no | no | no | yes | no
|
|
-- updatePost | rename only* | yes | if Δ | no | no | yes | no
|
|
-- publishPost | .md + trans | yes | yes | no | no | yes | no
|
|
-- deletePost | delete .md | del | del | no | Δ media | del | no
|
|
-- importMedia | copy file | yes | no | async | write | no | no
|
|
-- updateMedia | no | yes | no | no | rewrite | no | no
|
|
-- replaceMediaFile | overwrite | no | no | regen | no | no | no
|
|
-- deleteMedia | delete all | del | no | del | del all | no | no
|
|
-- createTemplate | .liquid | no | no | no | no | no | no
|
|
-- updateTemplate | rewrite | no | no | no | no | no | no
|
|
-- deleteTemplate | delete+casc | no | no | no | no | no | no
|
|
-- deleteTag | sync posts | no | no | no | no | no | tags.json
|
|
-- renameTag | sync posts | no | no | no | no | no | tags.json
|
|
-- mergeTags | sync posts | no | no | no | no | no | tags.json
|
|
-- updateMetadata | no | no | no | no | no | no | *.json
|
|
-- addCategory | no | no | no | no | no | no | *.json
|
|
-- * updatePost rewrites file only when templateSlug changes on published post
|