gazetta 0.6.0 → 0.8.0

package/dist/admin-api/routes/audit.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `GET /api/audit` — query forensic events from configured providers.
+ *
+ * Per design-audit.md "Audit drawer — query semantics":
+ * each provider is one of two query shapes:
+ *
+ *   - **Query-capable** — implements `query()`. Returns events
+ *     matching the filter. v1's `HistoryAuditProvider` is the only
+ *     in-tree implementation.
+ *   - **External-sink** — omits `query()`, optionally implements
+ *     `queryUrl()` returning a deep-link to the operator's
+ *     destination console.
+ *
+ * The route exposes BOTH: it asks every queryable provider for events
+ * matching the filter and merges them; for non-queryable providers it
+ * surfaces a `{ name, url }` reference that the drawer renders as a
+ * "View in CloudWatch" link (or "configured but not queryable" when
+ * `url` is null).
+ *
+ * # Why per-process providers, not per-source resolution
+ *
+ * Audit providers are admin-wide config (per `admin.audit` block),
+ * not per-target. The route receives the providers array directly
+ * from the boot block; same shape as `historyRoutes`.
+ *
+ * # Capability gating
+ *
+ * `read:audit-log` per design-audit.md and design-auth-rbac.md.
+ * Built-in role `admin` grants via root wildcard `*`. Built-in
+ * `editor` and `viewer` roles do NOT grant `read:audit-log` —
+ * the prefix wildcard `read:*` they hold is wildcard-exempt for
+ * audit (Cut 9). Operators wanting non-admin audit access declare
+ * a custom role with `['read:*', 'read:audit-log']` explicitly.
+ * Per design-auth-rbac.md "Audit-log read access is its own
+ * capability — viewers don't see audit by default."
+ *
+ * # Response merging
+ *
+ * Events from multiple queryable providers merge by sort order
+ * (newest first). Same-event dedup uses `(timestamp, actor.id,
+ * action, scope)` tuple — providers writing the same event to
+ * multiple sinks produce one logical event in the response.
+ *
+ * # Filter validation
+ *
+ * Action / outcome / scope.kind values are closed enums; the
+ * provider validates each filter field before delegating. Invalid
+ * values return 400 with the bad field. Missing filter fields are
+ * treated as "no filter on that dimension."
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: aggregator + dedup + filter parsing only. Doesn't audit
+ *     itself (the read isn't a write); doesn't write events.
+ *   - DIP: depends on `AuditProvider` interface, not on
+ *     `HistoryAuditProvider`. v2 sinks slot in unchanged.
+ *   - LSP: every provider's query result fits the same wire shape;
+ *     consumers branch only on `outcome` for behavior.
+ */
+import { Hono } from 'hono';
+import type { AuditProvider } from '../../audit/provider.js';
+export interface AuditRoutesOptions {
+    /**
+     * Configured audit providers, in operator declaration order. The
+     * route queries every provider implementing `query()`; non-
+     * queryable providers contribute their `queryUrl()` instead.
+     */
+    providers: ReadonlyArray<AuditProvider>;
+}
+export declare function auditRoutes(opts: AuditRoutesOptions): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=audit.d.ts.map

package/dist/admin-api/routes/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/admin-api/routes/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAK5D,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,SAAS,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;CACxC;AAKD,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,8EAmHnD"}

package/dist/admin-api/routes/audit.js

@@ -0,0 +1,178 @@
+/**
+ * `GET /api/audit` — query forensic events from configured providers.
+ *
+ * Per design-audit.md "Audit drawer — query semantics":
+ * each provider is one of two query shapes:
+ *
+ *   - **Query-capable** — implements `query()`. Returns events
+ *     matching the filter. v1's `HistoryAuditProvider` is the only
+ *     in-tree implementation.
+ *   - **External-sink** — omits `query()`, optionally implements
+ *     `queryUrl()` returning a deep-link to the operator's
+ *     destination console.
+ *
+ * The route exposes BOTH: it asks every queryable provider for events
+ * matching the filter and merges them; for non-queryable providers it
+ * surfaces a `{ name, url }` reference that the drawer renders as a
+ * "View in CloudWatch" link (or "configured but not queryable" when
+ * `url` is null).
+ *
+ * # Why per-process providers, not per-source resolution
+ *
+ * Audit providers are admin-wide config (per `admin.audit` block),
+ * not per-target. The route receives the providers array directly
+ * from the boot block; same shape as `historyRoutes`.
+ *
+ * # Capability gating
+ *
+ * `read:audit-log` per design-audit.md and design-auth-rbac.md.
+ * Built-in role `admin` grants via root wildcard `*`. Built-in
+ * `editor` and `viewer` roles do NOT grant `read:audit-log` —
+ * the prefix wildcard `read:*` they hold is wildcard-exempt for
+ * audit (Cut 9). Operators wanting non-admin audit access declare
+ * a custom role with `['read:*', 'read:audit-log']` explicitly.
+ * Per design-auth-rbac.md "Audit-log read access is its own
+ * capability — viewers don't see audit by default."
+ *
+ * # Response merging
+ *
+ * Events from multiple queryable providers merge by sort order
+ * (newest first). Same-event dedup uses `(timestamp, actor.id,
+ * action, scope)` tuple — providers writing the same event to
+ * multiple sinks produce one logical event in the response.
+ *
+ * # Filter validation
+ *
+ * Action / outcome / scope.kind values are closed enums; the
+ * provider validates each filter field before delegating. Invalid
+ * values return 400 with the bad field. Missing filter fields are
+ * treated as "no filter on that dimension."
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: aggregator + dedup + filter parsing only. Doesn't audit
+ *     itself (the read isn't a write); doesn't write events.
+ *   - DIP: depends on `AuditProvider` interface, not on
+ *     `HistoryAuditProvider`. v2 sinks slot in unchanged.
+ *   - LSP: every provider's query result fits the same wire shape;
+ *     consumers branch only on `outcome` for behavior.
+ */
+import { Hono } from 'hono';
+import { AuditActionSchema, AuditOutcomeSchema, AuditScopeKindSchema } from '../schemas/audit.js';
+import { requireCapability } from '../middleware/capability.js';
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 1000;
+export function auditRoutes(opts) {
+    const app = new Hono();
+    app.get('/api/audit', requireCapability('read:audit-log'), async (c) => {
+        // Filter parsing — closed enums validated against the schemas;
+        // invalid values surface as 400 (operator typo, not server bug).
+        const rawAction = c.req.query('action');
+        const rawOutcome = c.req.query('outcome');
+        const rawScopeKind = c.req.query('scopeKind');
+        const rawScopeName = c.req.query('scopeName');
+        const rawActor = c.req.query('actor');
+        const rawSince = c.req.query('since');
+        const rawUntil = c.req.query('until');
+        const rawLimit = c.req.query('limit');
+        const filter = {};
+        if (rawAction !== undefined) {
+            const parsed = AuditActionSchema.safeParse(rawAction);
+            if (!parsed.success) {
+                return c.json({ error: `Invalid action: "${rawAction}"` }, 400);
+            }
+            filter.action = parsed.data;
+        }
+        if (rawOutcome !== undefined) {
+            const parsed = AuditOutcomeSchema.safeParse(rawOutcome);
+            if (!parsed.success) {
+                return c.json({ error: `Invalid outcome: "${rawOutcome}"` }, 400);
+            }
+            filter.outcome = parsed.data;
+        }
+        if (rawScopeKind !== undefined || rawScopeName !== undefined) {
+            filter.scope = {};
+            if (rawScopeKind !== undefined) {
+                const parsed = AuditScopeKindSchema.safeParse(rawScopeKind);
+                if (!parsed.success) {
+                    return c.json({ error: `Invalid scopeKind: "${rawScopeKind}"` }, 400);
+                }
+                filter.scope.kind = parsed.data;
+            }
+            if (rawScopeName !== undefined)
+                filter.scope.name = rawScopeName;
+        }
+        if (rawActor !== undefined)
+            filter.actor = rawActor;
+        if (rawSince !== undefined)
+            filter.since = rawSince;
+        if (rawUntil !== undefined)
+            filter.until = rawUntil;
+        if (rawLimit !== undefined) {
+            const n = Number(rawLimit);
+            if (!Number.isFinite(n) || n <= 0) {
+                return c.json({ error: `Invalid limit: "${rawLimit}"` }, 400);
+            }
+            filter.limit = Math.min(Math.floor(n), MAX_LIMIT);
+        }
+        else {
+            filter.limit = DEFAULT_LIMIT;
+        }
+        // Fan-out: every queryable provider contributes events; every
+        // non-queryable provider contributes a sink reference. Both
+        // arrays return to the drawer; the UI composes the four states.
+        const queryableProviders = opts.providers.filter(p => typeof p.query === 'function');
+        const nonQueryable = opts.providers.filter(p => typeof p.query !== 'function');
+        const eventsFromProviders = await Promise.all(queryableProviders.map(async (p) => {
+            try {
+                // biome-ignore lint/style/noNonNullAssertion: filter above guarantees p.query is defined
+                return await p.query(filter);
+            }
+            catch {
+                // Per design-audit.md "query() failures are fail-open per
+                // Universal Provider Requirement #5": surface "audit query
+                // unavailable" without throwing. Empty result keeps the
+                // drawer rendering; operator's structured log catches the
+                // provider failure.
+                return [];
+            }
+        }));
+        // Merge + dedup + sort-newest-first. Per design-audit.md "Recommended
+        // operational pattern": run history + external-sink as peers; the
+        // drawer dedups the inline copies via `event.id` (we use a synthetic
+        // tuple since AuditEvent has no explicit id field — timestamp +
+        // actor + action + scope is unique per attempt by construction).
+        const seen = new Set();
+        const merged = [];
+        for (const events of eventsFromProviders) {
+            for (const event of events) {
+                const dedupKey = `${event.timestamp}:${event.actor.id}:${event.action}:${event.scope.kind}:${event.scope.name ?? ''}`;
+                if (seen.has(dedupKey))
+                    continue;
+                seen.add(dedupKey);
+                merged.push(event);
+            }
+        }
+        // Sort newest first so the drawer's default "most recent" view
+        // doesn't need client-side sorting. ISO-8601 strings sort
+        // correctly via localeCompare.
+        merged.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+        // Re-apply the limit at the merge layer — individual providers
+        // honor the limit per their own slice; merging two providers
+        // could exceed it.
+        const limited = merged.slice(0, filter.limit);
+        // External-sink references: name + queryUrl() (or null when not
+        // implemented or when queryUrl() returned null).
+        const externalSinks = nonQueryable.map(p => ({
+            name: p.name,
+            url: p.queryUrl?.() ?? null,
+        }));
+        const body = {
+            events: limited,
+            externalSinks,
+        };
+        return c.json(body);
+    });
+    return app;
+}
+//# sourceMappingURL=audit.js.map

package/dist/admin-api/routes/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../src/admin-api/routes/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAI3B,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AACjG,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAW/D,MAAM,aAAa,GAAG,GAAG,CAAA;AACzB,MAAM,SAAS,GAAG,IAAI,CAAA;AAEtB,MAAM,UAAU,WAAW,CAAC,IAAwB;IAClD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;IAEtB,GAAG,CAAC,GAAG,CAAC,YAAY,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,EAAE,KAAK,EAAC,CAAC,EAAC,EAAE;QACnE,+DAA+D;QAC/D,iEAAiE;QACjE,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;QACvC,MAAM,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;QACzC,MAAM,YAAY,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAA;QAC7C,MAAM,YAAY,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAA;QAC7C,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QACrC,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QACrC,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QACrC,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QAErC,MAAM,MAAM,GAAe,EAAE,CAAA;QAC7B,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;YACrD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,oBAAoB,SAAS,GAAG,EAAE,EAAE,GAAG,CAAC,CAAA;YACjE,CAAC;YACD,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,CAAA;QAC7B,CAAC;QACD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,UAAU,CAAC,CAAA;YACvD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,qBAAqB,UAAU,GAAG,EAAE,EAAE,GAAG,CAAC,CAAA;YACnE,CAAC;YACD,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,IAAI,CAAA;QAC9B,CAAC;QACD,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC7D,MAAM,CAAC,KAAK,GAAG,EAAE,CAAA;YACjB,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;gBAC/B,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,YAAY,CAAC,CAAA;gBAC3D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;oBACpB,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,uBAAuB,YAAY,GAAG,EAAE,EAAE,GAAG,CAAC,CAAA;gBACvE,CAAC;gBACD,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAA;YACjC,CAAC;YACD,IAAI,YAAY,KAAK,SAAS;gBAAE,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,YAAY,CAAA;QAClE,CAAC;QACD,IAAI,QAAQ,KAAK,SAAS;YAAE,MAAM,CAAC,KAAK,GAAG,QAAQ,CAAA;QACnD,IAAI,QAAQ,KAAK,SAAS;YAAE,MAAM,CAAC,KAAK,GAAG,QAAQ,CAAA;QACnD,IAAI,QAAQ,KAAK,SAAS;YAAE,MAAM,CAAC,KAAK,GAAG,QAAQ,CAAA;QACnD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;YAC1B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBAClC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,mBAAmB,QAAQ,GAAG,EAAE,EAAE,GAAG,CAAC,CAAA;YAC/D,CAAC;YACD,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAA;QACnD,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,KAAK,GAAG,aAAa,CAAA;QAC9B,CAAC;QAED,8DAA8D;QAC9D,4DAA4D;QAC5D,gEAAgE;QAChE,MAAM,kBAAkB,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,KAAK,KAAK,UAAU,CAAC,CAAA;QACpF,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,KAAK,KAAK,UAAU,CAAC,CAAA;QAE9E,MAAM,mBAAmB,GAAG,MAAM,OAAO,CAAC,GAAG,CAC3C,kBAAkB,CAAC,GAAG,CAAC,KAAK,EAAC,CAAC,EAAC,EAAE;YAC/B,IAAI,CAAC;gBACH,yFAAyF;gBACzF,OAAO,MAAM,CAAC,CAAC,KAAM,CAAC,MAAM,CAAC,CAAA;YAC/B,CAAC;YAAC,MAAM,CAAC;gBACP,0DAA0D;gBAC1D,2DAA2D;gBAC3D,wDAAwD;gBACxD,0DAA0D;gBAC1D,oBAAoB;gBACpB,OAAO,EAAkB,CAAA;YAC3B,CAAC;QACH,CAAC,CAAC,CACH,CAAA;QAED,sEAAsE;QACtE,kEAAkE;QAClE,qEAAqE;QACrE,gEAAgE;QAChE,iEAAiE;QACjE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;QAC9B,MAAM,MAAM,GAAiB,EAAE,CAAA;QAC/B,KAAK,MAAM,MAAM,IAAI,mBAAmB,EAAE,CAAC;YACzC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,MAAM,QAAQ,GAAG,GAAG,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,CAAA;gBACrH,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;oBAAE,SAAQ;gBAChC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;gBAClB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACpB,CAAC;QACH,CAAC;QACD,+DAA+D;QAC/D,0DAA0D;QAC1D,+BAA+B;QAC/B,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;QAC7D,+DAA+D;QAC/D,6DAA6D;QAC7D,mBAAmB;QACnB,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;QAE7C,gEAAgE;QAChE,iDAAiD;QACjD,MAAM,aAAa,GAA4B,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACpE,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,IAAI,IAAI;SAC5B,CAAC,CAAC,CAAA;QAEH,MAAM,IAAI,GAA2B;YACnC,MAAM,EAAE,OAA2B;YACnC,aAAa;SACd,CAAA;QACD,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrB,CAAC,CAAC,CAAA;IAEF,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/admin-api/routes/compare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../../src/admin-api/routes/compare.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAGnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAEjE,wBAAgB,aAAa,CAC3B,OAAO,EAAE,qBAAqB,EAC9B,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,EAC7C,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC5C,YAAY,CAAC,EAAE,MAAM,EACrB,qBAAqB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,8EAiE/F"}
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../../src/admin-api/routes/compare.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAGnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAGjE,wBAAgB,aAAa,CAC3B,OAAO,EAAE,qBAAqB,EAC9B,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,EAC7C,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC5C,YAAY,CAAC,EAAE,MAAM,EACrB,qBAAqB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,8EAiE/F"}

package/dist/admin-api/routes/compare.js

@@ -2,6 +2,7 @@ import { Hono } from 'hono';
 import { join } from 'node:path';
 import { getType } from '../../types.js';
 import { compareTargets } from '../../compare.js';
+import { requireCapability } from '../middleware/capability.js';
 export function compareRoutes(resolve, preInitTargets, targetConfigs, templatesDir, scanTemplatesInjected) {
     const app = new Hono();
     let targets = preInitTargets ?? null;
@@ -15,7 +16,7 @@ export function compareRoutes(resolve, preInitTargets, targetConfigs, templatesD
         }
         if (!targetsInitPromise) {
             const { createTargetRegistry } = await import('../../targets.js');
-            targetsInitPromise = createTargetRegistry(targetConfigs, projectSiteDir)
+            targetsInitPromise = createTargetRegistry(targetConfigs)
                 .then(t => {
                 targets = t;
                 return t;
@@ -27,7 +28,7 @@ export function compareRoutes(resolve, preInitTargets, targetConfigs, templatesD
         }
         return targetsInitPromise;
     }
-    app.get('/api/compare', async (c) => {
+    app.get('/api/compare', requireCapability('read:pages'), async (c) => {
         // `target` = compare destination (what we're diffing against)
         // `source` = source of the compare (which editable target to read from);
         //           defaults to the resolver's default editable target

package/dist/admin-api/routes/compare.js.map

@@ -1 +1 @@
-{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../../src/admin-api/routes/compare.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../../src/admin-api/routes/compare.ts"],"names":[],"mappings":"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"}

package/dist/admin-api/routes/fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../../src/admin-api/routes/fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAG3B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAIjE,wBAAgB,WAAW,CAAC,OAAO,EAAE,qBAAqB,EAAE,QAAQ,CAAC,EAAE,MAAM,8EAyB5E"}
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../../src/admin-api/routes/fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAG3B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAKjE,wBAAgB,WAAW,CAAC,OAAO,EAAE,qBAAqB,EAAE,QAAQ,CAAC,EAAE,MAAM,8EAyB5E"}

package/dist/admin-api/routes/fields.js

@@ -1,12 +1,13 @@
 import { Hono } from 'hono';
 import { join } from 'node:path';
 import { createFilesystemProvider } from '../../providers/filesystem.js';
+import { requireCapability } from '../middleware/capability.js';
 const FIELD_EXTENSIONS = ['.ts', '.tsx'];
 export function fieldRoutes(resolve, adminDir) {
     const app = new Hono();
     // Custom fields live at project level, outside target content storage.
     const storage = createFilesystemProvider();
-    app.get('/api/fields', async (c) => {
+    app.get('/api/fields', requireCapability('read:pages'), async (c) => {
         // projectSiteDir is target-invariant (it's the on-disk project path).
         // We still go through resolve() so the single source-lookup codepath
         // serves this route too — keeps the handler shape uniform.

package/dist/admin-api/routes/fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"fields.js","sourceRoot":"","sources":["../../../src/admin-api/routes/fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAC3B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAGxE,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AAExC,MAAM,UAAU,WAAW,CAAC,OAA8B,EAAE,QAAiB;IAC3E,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;IACtB,uEAAuE;IACvE,MAAM,OAAO,GAAG,wBAAwB,EAAE,CAAA;IAE1C,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,EAAC,CAAC,EAAC,EAAE;QAC/B,sEAAsE;QACtE,qEAAqE;QACrE,2DAA2D;QAC3D,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAA;QACnD,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAA;QAElF,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAEzD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QAChD,MAAM,MAAM,GAAG,OAAO;aACnB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,IAAI,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;aACjF,GAAG,CAAC,CAAC,CAAC,EAAE;YACP,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAA;YAC9C,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAA;QAChD,CAAC,CAAC,CAAA;QACJ,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACvB,CAAC,CAAC,CAAA;IAEF,OAAO,GAAG,CAAA;AACZ,CAAC"}
+{"version":3,"file":"fields.js","sourceRoot":"","sources":["../../../src/admin-api/routes/fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAC3B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAExE,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAE/D,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AAExC,MAAM,UAAU,WAAW,CAAC,OAA8B,EAAE,QAAiB;IAC3E,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;IACtB,uEAAuE;IACvE,MAAM,OAAO,GAAG,wBAAwB,EAAE,CAAA;IAE1C,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,iBAAiB,CAAC,YAAY,CAAC,EAAE,KAAK,EAAC,CAAC,EAAC,EAAE;QAChE,sEAAsE;QACtE,qEAAqE;QACrE,2DAA2D;QAC3D,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAA;QACnD,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAA;QAElF,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAEzD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QAChD,MAAM,MAAM,GAAG,OAAO;aACnB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,IAAI,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;aACjF,GAAG,CAAC,CAAC,CAAC,EAAE;YACP,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAA;YAC9C,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAA;QAChD,CAAC,CAAC,CAAA;QACJ,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACvB,CAAC,CAAC,CAAA;IAEF,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/admin-api/routes/fragments.d.ts

@@ -1,4 +1,16 @@
 import { Hono } from 'hono';
 import type { SourceContextResolver } from '../source-context.js';
-export declare function fragmentRoutes(resolve: SourceContextResolver): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+import type { ValidatorRegistry } from '../../validation/registry.js';
+import type { AuditEnv } from '../middleware/audit.js';
+import { type HookRegistry } from '../../hooks/index.js';
+export interface FragmentRoutesOptions {
+    hooks?: HookRegistry;
+    /**
+     * Background validation scanner. Fragment saves notify the scanner to
+     * re-validate this fragment + every page/fragment that references it
+     * (transitively, via `findDependentsFromSidecars`).
+     */
+    scanner?: import('../../validation/scanner.js').ValidationScanner | null;
+}
+export declare function fragmentRoutes(resolve: SourceContextResolver, validators: ValidatorRegistry, templatesDir?: string, opts?: FragmentRoutesOptions): Hono<AuditEnv, import("hono/types").BlankSchema, "/">;
 //# sourceMappingURL=fragments.d.ts.map

package/dist/admin-api/routes/fragments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fragments.d.ts","sourceRoot":"","sources":["../../../src/admin-api/routes/fragments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAI3B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAIjE,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,8EAmJ5D"}
+{"version":3,"file":"fragments.d.ts","sourceRoot":"","sources":["../../../src/admin-api/routes/fragments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAIjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAGrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACtD,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAK7F,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,6BAA6B,EAAE,iBAAiB,GAAG,IAAI,CAAA;CACzE;AAED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,qBAAqB,EAC9B,UAAU,EAAE,iBAAiB,EAC7B,YAAY,CAAC,EAAE,MAAM,EACrB,IAAI,GAAE,qBAA0B,yDA0MjC"}

package/dist/admin-api/routes/fragments.js

@@ -1,15 +1,28 @@
 import { Hono } from 'hono';
-import { join } from 'node:path';
 import { loadSiteFromSource } from '../source-context.js';
-import { recordWrite } from '../../history-recorder.js';
 import { CreateFragmentRequestSchema } from '../schemas/fragments.js';
 import { isValidLocale } from '../../locale.js';
-export function fragmentRoutes(resolve) {
+import { FRAGMENT_HANDLE, handleArchive, handlePurge } from './archive.js';
+import { computeSaveEtag } from '../../save-etag.js';
+import { requireCapability } from '../middleware/capability.js';
+import { buildHookContext, dispatchAfterLoad } from '../../hooks/index.js';
+import { makeAuditFiringEmitter } from '../hook-audit-emitter.js';
+import { FragmentNotFoundError, InvalidLocaleError, saveFragment } from '../../fragments/save.js';
+import { createFragment } from '../../fragments/create.js';
+export function fragmentRoutes(resolve, validators, templatesDir, opts = {}) {
     const app = new Hono();
-    app.get('/api/fragments', async (c) => {
+    const hooks = opts.hooks;
+    app.get('/api/fragments', requireCapability('read:fragments'), async (c) => {
         const source = await resolve(c.req.query('target'));
         // Empty target → empty list. See pages.ts for rationale.
         try {
+            // Cache the summary list (see pages.ts for the rationale + the
+            // target-scoping invariant per design-cache.md Gap 6).
+            const targetKey = source.targetName ?? '__source__';
+            const cacheKey = `fragments:summary:target:${targetKey}`;
+            const cached = await source.cache.get(cacheKey);
+            if (cached)
+                return c.json(cached);
             const site = await loadSiteFromSource(source);
             const fragments = [...site.fragments.entries()].map(([name, frag]) => {
                 const localeEntry = site.fragmentLocales.get(name);
@@ -17,20 +30,25 @@ export function fragmentRoutes(resolve) {
                     name,
                     template: frag.template,
                     locales: localeEntry ? [...localeEntry.locales.keys()] : undefined,
+                    // Archive surfacing per design-soft-delete.md Q7 J1.
+                    ...(frag.archived === true ? { archived: true } : {}),
+                    ...(frag.aliasOf ? { aliasOf: frag.aliasOf } : {}),
                 };
             });
+            await source.cache.set(cacheKey, fragments);
             return c.json(fragments);
         }
         catch (err) {
             const msg = err.message;
-            if (msg.includes('No site.yaml found'))
+            if (msg.includes('loadSite:'))
                 return c.json([]);
             throw err;
         }
     });
-    app.post('/api/fragments', async (c) => {
+    // POST delegates to `fragments/create.ts` — same protocol-thin
+    // shape as pages POST.
+    app.post('/api/fragments', requireCapability('edit:fragments'), async (c) => {
         const source = await resolve(c.req.query('target'));
-        const { storage, sidecarWriter } = source;
         // Schema-validate the body — same rationale as pages.ts.
         const raw = await c.req.json();
         const parsed = CreateFragmentRequestSchema.safeParse(raw);
@@ -41,18 +59,29 @@ export function fragmentRoutes(resolve) {
             }, 400);
         }
         const body = parsed.data;
-        const fragDir = source.contentRoot.path('fragments', body.name);
-        const manifestPath = join(fragDir, 'fragment.json');
-        if (await storage.exists(manifestPath)) {
-            return c.json({ error: `Fragment "${body.name}" already exists` }, 409);
+        const result = await createFragment({
+            name: body.name,
+            template: body.template,
+            onConflict: c.req.query('onConflict'),
+            source,
+            principal: c.var.principal,
+            audit: c.var.audit,
+        });
+        if (result.ok) {
+            return c.json(result.resolution
+                ? { ok: true, name: result.name, resolution: result.resolution }
+                : { ok: true, name: result.name });
+        }
+        if (result.code === 'LIVE_CONFLICT') {
+            return c.json({ error: `Fragment "${result.name}" already exists` }, 409);
         }
-        await storage.mkdir(fragDir);
-        const manifest = { template: body.template, components: [] };
-        await storage.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
-        await sidecarWriter?.writeFor('fragment', body.name);
-        return c.json({ ok: true, name: body.name });
+        if (result.code === 'ARCHIVED_CONFLICT') {
+            return c.json({ code: 'ARCHIVED_NAME_CONFLICT', archive: result.archive }, 409);
+        }
+        // INVALID_CONFLICT_MODE — exhaustive narrow.
+        return c.json({ error: `Invalid onConflict mode "${result.mode}"` }, 400);
     });
-    app.get('/api/fragments/:name', async (c) => {
+    app.get('/api/fragments/:name', requireCapability('read:fragments'), async (c) => {
         const name = c.req.param('name');
         const rawLocale = c.req.query('locale');
         const locale = rawLocale && isValidLocale(rawLocale) ? rawLocale.toLowerCase() : undefined;
@@ -72,7 +101,15 @@ export function fragmentRoutes(resolve) {
         if (!fragment)
             return c.json({ error: `Fragment "${name}" not found` }, 404);
         const localeEntry = site.fragmentLocales.get(name);
-        return c.json({
+        // Save-concurrency etag — see save-etag.ts. Same shape as pages
+        // (without metadata + route since fragments don't carry them).
+        const etag = await computeSaveEtag({
+            template: fragment.template,
+            content: fragment.content,
+            components: fragment.components,
+        });
+        c.header('ETag', `"${etag}"`);
+        let body = {
             name,
             template: fragment.template,
             content: fragment.content,
@@ -80,64 +117,88 @@ export function fragmentRoutes(resolve) {
             dir: fragment.dir,
             locale: locale ?? undefined,
             locales: localeEntry ? [...localeEntry.locales.keys()] : undefined,
-        });
+            // Archive fields per design-soft-delete.md Q1 A1. See pages.ts.
+            ...(fragment.archived === true ? { archived: true } : {}),
+            ...(fragment.archivedAt ? { archivedAt: fragment.archivedAt } : {}),
+            ...(fragment.archivedBy ? { archivedBy: fragment.archivedBy } : {}),
+            ...(fragment.aliasOf ? { aliasOf: fragment.aliasOf } : {}),
+        };
+        // afterLoad hooks per design-hooks.md "Save flow with hooks":
+        // mutating chain at read time. See pages.ts for rationale.
+        if (hooks) {
+            const ctx = buildHookContext({
+                principal: c.var.principal,
+                storage: source.storage,
+                target: source.targetName,
+                requestId: c.req.header('x-request-id') ?? crypto.randomUUID(),
+                site: { name: source.manifest?.name },
+                auditEmit: makeAuditFiringEmitter(c.var.audit),
+            });
+            body = await dispatchAfterLoad(hooks, { kind: 'fragment', name, locale: locale ?? undefined }, body, ctx);
+        }
+        return c.json(body);
     });
-    app.put('/api/fragments/:name', async (c) => {
+    // PUT delegates to `fragments/save.ts` — the spine lives in
+    // `manifest-save.ts` (per Cut 2). This handler is now a protocol
+    // translator: parse Hono request → call `saveFragment` → project
+    // `SaveResult` to HTTP. Same response shape as before.
+    app.put('/api/fragments/:name', requireCapability('edit:fragments'), async (c) => {
         const name = c.req.param('name');
         const rawLocale = c.req.query('locale');
-        const locale = rawLocale && isValidLocale(rawLocale) ? rawLocale.toLowerCase() : undefined;
-        if (rawLocale && !locale)
-            return c.json({ error: `Invalid locale code: "${rawLocale}"` }, 400);
         const source = await resolve(c.req.query('target'));
-        const { storage, sidecarWriter } = source;
-        const site = await loadSiteFromSource(source);
-        const defaultFragment = site.fragments.get(name);
-        if (!defaultFragment)
-            return c.json({ error: `Fragment "${name}" not found` }, 404);
-        const localeVariant = locale ? site.fragmentLocales.get(name)?.locales.get(locale) : undefined;
-        const fragment = localeVariant ?? defaultFragment;
+        const site = await loadSiteFromSource(source, { templatesDir });
+        // RFC-7232 If-Match is quoted; normalize before passing through.
+        const ifMatchRaw = c.req.header('If-Match');
+        const ifMatch = ifMatchRaw?.replace(/^"(.*)"$/, '$1');
         const body = await c.req.json();
-        const manifest = {
-            template: body.template ?? fragment.template,
-            content: body.content ?? fragment.content,
-            components: body.components ?? fragment.components,
-        };
-        const filename = locale ? `fragment.${locale}.json` : 'fragment.json';
-        const manifestPath = join(defaultFragment.dir, filename);
-        const serialized = JSON.stringify(manifest, null, 2) + '\n';
-        // History first — see pages.ts PUT handler rationale (baseline must
-        // capture pre-write state).
-        if (source.history) {
-            await recordWrite({
-                history: source.history,
-                contentRoot: source.contentRoot,
-                operation: 'save',
-                items: [{ path: source.contentRoot.relative(manifestPath), content: serialized }],
+        let result;
+        try {
+            result = await saveFragment({
+                name,
+                locale: rawLocale,
+                body,
+                ifMatch,
+                site,
+                source,
+                principal: c.var.principal,
+                audit: c.var.audit,
+                validators,
+                hooks,
+                hookAuditEmit: makeAuditFiringEmitter(c.var.audit),
+                scanner: opts.scanner ?? undefined,
+                requestId: c.req.header('x-request-id') ?? undefined,
             });
         }
-        await storage.writeFile(manifestPath, serialized);
-        await sidecarWriter?.writeFor('fragment', name);
-        return c.json({ ok: true });
-    });
-    app.delete('/api/fragments/:name', async (c) => {
-        const name = c.req.param('name');
-        const source = await resolve(c.req.query('target'));
-        const { storage } = source;
-        const site = await loadSiteFromSource(source);
-        const fragment = site.fragments.get(name);
-        if (!fragment)
-            return c.json({ error: `Fragment "${name}" not found` }, 404);
-        const manifestPath = join(fragment.dir, 'fragment.json');
-        if (source.history) {
-            await recordWrite({
-                history: source.history,
-                contentRoot: source.contentRoot,
-                operation: 'save',
-                items: [{ path: source.contentRoot.relative(manifestPath), content: null }],
+        catch (err) {
+            if (err instanceof InvalidLocaleError)
+                return c.json({ error: err.message }, 400);
+            if (err instanceof FragmentNotFoundError)
+                return c.json({ error: err.message }, 404);
+            throw err;
+        }
+        if (result.ok) {
+            c.header('ETag', `"${result.etag}"`);
+            return c.json({ ok: true, etag: result.etag });
+        }
+        if (result.code === 'STALE') {
+            return c.json({ code: 'STALE', current: result.current, currentEtag: result.currentEtag }, 409, {
+                ETag: `"${result.currentEtag}"`,
             });
         }
-        await storage.rm(fragment.dir);
-        return c.json({ ok: true });
+        if (result.code === 'VALIDATION_FAILED') {
+            return c.json({ code: 'VALIDATION_FAILED', issues: result.issues }, 409);
+        }
+        // HOOK_CANCELLED — exhaustive narrow per Q1 lock.
+        return c.json({ code: 'HOOK_CANCELLED', hook: result.hook, reason: result.reason }, 409);
+    });
+    // DELETE = soft-delete (archive) by default per Cut 7 cutover.
+    // `?permanent=true` invokes purge for explicit hard-delete intent.
+    // See pages.ts for the full rationale; same shape applies here.
+    app.delete('/api/fragments/:name', requireCapability('delete:fragments'), async (c) => {
+        const permanent = c.req.query('permanent') === 'true';
+        if (permanent)
+            return handlePurge(c, resolve, FRAGMENT_HANDLE);
+        return handleArchive(c, resolve, FRAGMENT_HANDLE);
     });
     return app;
 }