immutable-design-guard

Validate Knowledge Home code changes against immutable data model invariants.

9|4|Updated May 30, 2025
One-click install
npx skills add https://github.com/Kaikei-e/Alt --skill immutable-design-guard
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: immutable-design-guard
Source: https://github.com/Kaikei-e/Alt/tree/main/.claude/skills/immutable-design-guard
Command: npx skills add https://github.com/Kaikei-e/Alt --skill immutable-design-guard

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps engineers and reviewers verify that changes to Knowledge Home do not violate the immutable data model and Alt canonical contract by detecting patterns that undermine append-only event modeling, reprojectability, and projection versioning.

Core Features & Use Cases

  • Append-first validation: Detects updates or deletes against event tables and checks for missing idempotency keys.
  • Resource vs Event separation checks: Flags attempts to conflate resource rows with time-based events or to hide events behind updated_at fields.
  • Event timestamp and projector checks: Ensures events carry a single business time and projectors rely on event times rather than runtime Now.
  • Reproject-safe and disposable projection audits: Looks for reads of latest-state in projectors, direct projection mutations, and projection_version misuse.
  • Versioning and why semantics: Verifies summary/tag version append semantics, permissioned why codes, and merge-safe upserts for summary_state and dismissed_at.
  • Actionable reporting: Produces short Immutable Design Findings with severity, violated principle names, why it's dangerous, and event-first alternatives.

Quick Start

Run the immutable-design-guard to audit proposed changes touching knowledge_events, projector logic, or projection tables and produce an Immutable Design Findings report.

Frequently Asked Questions about immutable-design-guard

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I validate append-only event modeling invariants during a code review?

To validate append-only event modeling invariants during code review, run an immutable design guard to detect updates or deletes against event tables and verify the presence of idempotency keys. It generates a findings report detailing severity, violated principles, and event-first alternatives.

What is reproject-safe projector behavior in event sourcing?

Reproject-safe projector behavior in event sourcing requires projectors to rely on event times rather than runtime Now, avoid reading latest-state, and prevent direct projection mutations. This ensures projections remain disposable and can be deterministically rebuilt from the event log.

How do I enforce versioned artifacts and why-first semantics in projection tables?

To enforce versioned artifacts and why-first semantics in projection tables, audit summary and tag version append semantics to verify permissioned why codes and merge-safe upserts for summary_state and dismissed_at. This maintains strict canonical version control over derived artifacts.

Does event sourcing require separating resource rows from time-based events?

Yes, event sourcing requires separating resource rows from time-based events to prevent conflating them or hiding events behind updated_at fields. This separation ensures all state changes are captured explicitly as immutable, append-only events.

When should I use an immutable design guard for event-sourced projections?

You should use an immutable design guard during code review, refactoring, or feature work whenever modifications touch knowledge_events, projector logic, reproject mechanisms, summary_versions, or related projection views to ensure canonical invariants are not violated.

What are common limitations of manually auditing event-sourced projection mutations?

Manually auditing event-sourced projection mutations often misses subtle issues like projection_version misuse, direct projection mutations, or projectors reading latest-state, which undermines reprojectability and disposable projections without automated grep-based detection patterns.