@vxil/feature-configs 0.4.0 → 0.5.0

package/src/apiState.ts

@@ -0,0 +1,347 @@
+// DECLARED API STATE — the pure declared-vs-live planner (roadmap §4.11 P0-3,
+// 2026-09-23).
+//
+// Three datums used to be API state OUTSIDE vxil.config — rows their own /v1
+// route created, that `vxil push` never converged and a rollback never
+// restored — so every tenant that wanted a reproducible second environment
+// wrote an `ensure-*.ts` script and a nightly assert (the cvskit evaluation,
+// §8 P1-7). They are now DECLARED in the feature's config block and CONVERGED
+// by `vxil push` and `POST /v1/apply`:
+//
+//   rate-limits.policies[]     — keyed by `name`      (POST/PUT/DELETE /v1/rate-limits/policies)
+//   webhooks.subscriptions[]   — keyed by `target_url` (POST/DELETE /v1/webhooks/subscriptions)
+//   ai.templates[]             — keyed by `template`   (POST /v1/ai/templates, by content hash)
+//
+// ONE WRITER PER DATUM, AND THE WRITER IS THE REPOSITORY. The planner below is
+// PURE (no I/O, no clock): it takes the declared list and the live rows and
+// returns the exact operation set. Two executors drive it against two
+// transports — the control-plane (handlers/apiState.ts: the feature's own
+// routes with the caller's scopes, or its own table in-process) and the CLI
+// (packages/cli/src/apiState.ts: the tenant's API key) — and a parity test pins
+// that the same fixtures produce the same plan on both, the cms-schema
+// precedent.
+//
+// THE NON-DESTRUCTIVE DEFAULT. A live row the config does NOT declare is
+// LEFT IN PLACE and reported as `undeclared` — deleted only when the caller
+// passes allow-destructive — so adopting a block on an existing tenant is a
+// report, never a wipe. A change that can only be applied by delete+recreate
+// (a policy's `key_template`; a subscription's prefix set) is likewise
+// destructive-SHAPED: it changes the row's id, which a caller may have
+// cached, so it is reported and applied only under the same ack.
+//
+// Two shapes this file deliberately does NOT cover, with the reason:
+//   notifications.templates — templates are CODE with per-locale `overrides`
+//     already in config (templates.overrides); there is no stored-template row.
+//   notifications.campaigns — a campaign is a lifecycle row (draft → scheduled
+//     → sending → …) with runtime state; declaring it would re-send.
+import type { DeclaredRlPolicy, DeclaredWebhookSubscription } from './index.js';
+
+/** The target_url path markers of the platform's function-delivery lanes
+ *  (control-plane fnCmsHooks.ts FN_CMSHOOK_PATH / FN_AUTHHOOK_PATH /
+ *  FN_WEBHOOK_TRIGGER_PATH — mirrored here because this package is
+ *  typebox-only). A subscription on one of them is derived from the functions
+ *  manifest by the deploy reconciler: never declarable, never "undeclared". */
+export const FN_TRIGGER_TARGET_MARKERS = [
+  '/v1/internal/fn/cms-hook/',
+  '/v1/internal/fn/auth-hook/',
+  '/v1/internal/fn/trigger/',
+] as const;
+export function isFnTriggerSubscriptionUrl(targetUrl: string): boolean {
+  return FN_TRIGGER_TARGET_MARKERS.some((m) => targetUrl.includes(m));
+}
+
+export type ApiStateDatum = 'policies' | 'subscriptions' | 'templates';
+
+/** feature → the declared-API-state datum its config block may carry. */
+export const API_STATE_DATUMS: ReadonlyArray<{ feature: string; datum: ApiStateDatum }> = [
+  { feature: 'rate-limits', datum: 'policies' },
+  { feature: 'webhooks', datum: 'subscriptions' },
+  { feature: 'ai', datum: 'templates' },
+];
+
+export function apiStateDatumOf(feature: string): ApiStateDatum | null {
+  return API_STATE_DATUMS.find((d) => d.feature === feature)?.datum ?? null;
+}
+
+/** The declared list a validated manifest carries for its feature's datum, or
+ *  null when the feature has no datum / the block is absent. An absent block
+ *  means "not managed by config" (nothing converges, nothing is reported) —
+ *  distinct from an EMPTY array, which declares "there should be none". */
+export function declaredApiState(
+  feature: string, manifest: Record<string, unknown> | null | undefined,
+): { datum: ApiStateDatum; declared: unknown[] } | null {
+  const datum = apiStateDatumOf(feature);
+  if (!datum || !manifest) return null;
+  const list = manifest[datum];
+  if (!Array.isArray(list)) return null;
+  return { datum, declared: list };
+}
+
+// ── rate-limits policies ─────────────────────────────────────────────────────
+
+/** ONE row of GET /v1/rate-limits/policies (rate-limits-v1 core.ts Policy). */
+export interface LiveRlPolicy {
+  policy_id: string;
+  name: string;
+  key_template: string;
+  limit: number;
+  window_seconds: number;
+  behavior: string;
+  /** absent on a policy stored before the token-bucket pass → 'sliding_window' */
+  algorithm?: string;
+}
+
+/** The PUT /v1/rate-limits/policies/:id body the converge sends (core.ts
+ *  UpdateBody minus `name`, which is the key). */
+export interface RlPolicyPatch {
+  limit?: number;
+  window_seconds?: number;
+  behavior?: 'block' | 'shape';
+  algorithm?: 'sliding_window' | 'token_bucket';
+}
+
+export const RL_DEFAULT_BEHAVIOR = 'block' as const;
+export const RL_DEFAULT_ALGORITHM = 'sliding_window' as const;
+
+export interface RlPolicyPlan {
+  create: DeclaredRlPolicy[];
+  update: Array<{ policy_id: string; name: string; patch: RlPolicyPatch; changed: string[] }>;
+  /** `key_template` differs — the update route cannot change it, so the only
+   *  fix is delete+recreate (a NEW policy_id): destructive-shaped. */
+  recreate: Array<{ policy_id: string; name: string; declared: DeclaredRlPolicy }>;
+  unchanged: string[];
+  /** live rows the config does not declare (left in place by default) */
+  undeclared: Array<{ policy_id: string; name: string }>;
+  /** a declared name matched by MORE THAN ONE live row — names are not a
+   *  unique key on the route, so the converge cannot pick; nothing is touched */
+  ambiguous: Array<{ name: string; count: number }>;
+}
+
+export function planRlPolicies(
+  declared: readonly DeclaredRlPolicy[], live: readonly LiveRlPolicy[],
+): RlPolicyPlan {
+  const plan: RlPolicyPlan = { create: [], update: [], recreate: [], unchanged: [], undeclared: [], ambiguous: [] };
+  const byName = new Map<string, LiveRlPolicy[]>();
+  for (const row of live) byName.set(row.name, [...(byName.get(row.name) ?? []), row]);
+  const declaredNames = new Set(declared.map((d) => d.name));
+  for (const d of declared) {
+    const rows = byName.get(d.name) ?? [];
+    if (rows.length === 0) { plan.create.push(d); continue; }
+    if (rows.length > 1) { plan.ambiguous.push({ name: d.name, count: rows.length }); continue; }
+    const l = rows[0]!;
+    if (l.key_template !== d.key_template) { plan.recreate.push({ policy_id: l.policy_id, name: d.name, declared: d }); continue; }
+    const patch: RlPolicyPatch = {};
+    const changed: string[] = [];
+    if (d.limit !== undefined && d.limit !== l.limit) { patch.limit = d.limit; changed.push('limit'); }
+    if (d.window_seconds !== undefined && d.window_seconds !== l.window_seconds) { patch.window_seconds = d.window_seconds; changed.push('window_seconds'); }
+    const wantBehavior: 'block' | 'shape' = d.behavior ?? RL_DEFAULT_BEHAVIOR;
+    if (wantBehavior !== l.behavior) { patch.behavior = wantBehavior; changed.push('behavior'); }
+    const wantAlgorithm: 'sliding_window' | 'token_bucket' = d.algorithm ?? RL_DEFAULT_ALGORITHM;
+    if (wantAlgorithm !== (l.algorithm ?? RL_DEFAULT_ALGORITHM)) { patch.algorithm = wantAlgorithm; changed.push('algorithm'); }
+    if (changed.length) plan.update.push({ policy_id: l.policy_id, name: d.name, patch, changed });
+    else plan.unchanged.push(d.name);
+  }
+  for (const row of live) {
+    if (!declaredNames.has(row.name)) plan.undeclared.push({ policy_id: row.policy_id, name: row.name });
+  }
+  return plan;
+}
+
+// ── webhooks subscriptions ───────────────────────────────────────────────────
+
+/** ONE row of GET /v1/webhooks/subscriptions (state 'deleted' never listed). */
+export interface LiveWebhookSubscription {
+  sub_id: string;
+  target_url: string;
+  event_prefixes: string[];
+  state?: string;
+}
+
+export interface WebhookSubscriptionPlan {
+  create: DeclaredWebhookSubscription[];
+  /** the prefix SET differs — there is no update route, so delete+recreate (a
+   *  NEW sub_id, and the watermark restarts at "now"): destructive-shaped. */
+  recreate: Array<{ sub_id: string; target_url: string; declared: DeclaredWebhookSubscription }>;
+  unchanged: string[];
+  /** live rows the config does not declare, EXCLUDING the function-delivery
+   *  lanes (those derive from the functions manifest) — left in place by default */
+  undeclared: Array<{ sub_id: string; target_url: string }>;
+}
+
+function sameStringSet(a: readonly string[], b: readonly string[]): boolean {
+  const A = new Set(a); const B = new Set(b);
+  return A.size === B.size && [...A].every((x) => B.has(x));
+}
+
+export function planWebhookSubscriptions(
+  declared: readonly DeclaredWebhookSubscription[], live: readonly LiveWebhookSubscription[],
+): WebhookSubscriptionPlan {
+  const plan: WebhookSubscriptionPlan = { create: [], recreate: [], unchanged: [], undeclared: [] };
+  const declaredUrls = new Set(declared.map((d) => d.target_url));
+  const matched = new Set<string>();
+  for (const d of declared) {
+    const want = d.event_prefixes ?? [];
+    const rows = live.filter((l) => l.target_url === d.target_url);
+    if (rows.length === 0) { plan.create.push(d); continue; }
+    // Prefer an EXACT prefix-set match among duplicates (a hand-made row equal
+    // to the declaration is adopted as-is — no churn); else the first row is
+    // the one recreated and the rest fall through as undeclared duplicates.
+    const exact = rows.find((l) => sameStringSet(l.event_prefixes ?? [], want));
+    const chosen = exact ?? rows[0]!;
+    matched.add(chosen.sub_id);
+    if (exact) plan.unchanged.push(d.target_url);
+    else plan.recreate.push({ sub_id: chosen.sub_id, target_url: d.target_url, declared: d });
+  }
+  for (const l of live) {
+    if (matched.has(l.sub_id)) continue;
+    if (isFnTriggerSubscriptionUrl(l.target_url)) continue; // manifest-derived, never ours
+    if (declaredUrls.has(l.target_url)) {
+      // a duplicate live row for a declared url — surplus, not the adopted one
+      plan.undeclared.push({ sub_id: l.sub_id, target_url: l.target_url });
+      continue;
+    }
+    plan.undeclared.push({ sub_id: l.sub_id, target_url: l.target_url });
+  }
+  return plan;
+}
+
+// ── ai templates ─────────────────────────────────────────────────────────────
+
+/** ONE row of GET /v1/ai/templates. `content_sha256` is the canonical hash of
+ *  the LATEST version's {system,user,schema} (@vxil/runtime
+ *  aiTemplateContentSha256), stamped by ai-v1 since 2026-09-23; absent on an
+ *  older server. */
+export interface LiveAiTemplate {
+  name: string;
+  latest_version: number;
+  content_sha256?: string;
+}
+
+/** A declared template with its content hash pre-computed by the caller (the
+ *  hash is async WebCrypto; this planner stays pure/sync). */
+export interface HashedDeclaredAiTemplate {
+  template: string;
+  content_sha256: string;
+}
+
+export interface AiTemplatePlan {
+  create: string[];
+  /** content differs → POST a new version (monotonic per name) */
+  update: string[];
+  unchanged: string[];
+  /** stored names the config does not declare — there is NO delete route for
+   *  templates, so these are only ever reported, never removed */
+  undeclared: string[];
+  /** live rows with no `content_sha256` (an older server): the content cannot
+   *  be compared, so each is re-put as `update` and named here */
+  unknownContent: string[];
+}
+
+export function planAiTemplates(
+  declared: readonly HashedDeclaredAiTemplate[], live: readonly LiveAiTemplate[],
+): AiTemplatePlan {
+  const plan: AiTemplatePlan = { create: [], update: [], unchanged: [], undeclared: [], unknownContent: [] };
+  const byName = new Map(live.map((l) => [l.name, l]));
+  const declaredNames = new Set(declared.map((d) => d.template));
+  for (const d of declared) {
+    const l = byName.get(d.template);
+    if (!l) { plan.create.push(d.template); continue; }
+    if (l.content_sha256 === undefined) { plan.unknownContent.push(d.template); plan.update.push(d.template); continue; }
+    if (l.content_sha256 === d.content_sha256) plan.unchanged.push(d.template);
+    else plan.update.push(d.template);
+  }
+  for (const l of live) if (!declaredNames.has(l.name)) plan.undeclared.push(l.name);
+  return plan;
+}
+
+// ── the converge SUMMARY (what `vxil push` prints, what the journal stores) ──
+
+export interface ApiStateSummary {
+  datum: ApiStateDatum;
+  created: string[];
+  updated: string[];
+  /** destructive-shaped changes APPLIED under allow-destructive (delete+recreate) */
+  recreated: string[];
+  unchanged: string[];
+  /** live rows the config does not declare — left in place (or, under
+   *  allow-destructive, listed in `deleted` instead) */
+  undeclared: string[];
+  /** undeclared rows DELETED under allow-destructive */
+  deleted: string[];
+  /** destructive-shaped changes NOT applied (need allow-destructive) */
+  pending_destructive: string[];
+  /** declared keys the converge could not resolve (duplicate live rows) */
+  ambiguous: string[];
+  /** rows a route refused (a 4xx) — the converge continues past them */
+  failed: Array<{ key: string; error: string }>;
+}
+
+export function emptyApiStateSummary(datum: ApiStateDatum): ApiStateSummary {
+  return {
+    datum, created: [], updated: [], recreated: [], unchanged: [], undeclared: [],
+    deleted: [], pending_destructive: [], ambiguous: [], failed: [],
+  };
+}
+
+/** The `api_state` object a config-write response carries (`PUT /v1/config/
+ *  :feature` and its dashboard twin, dry-run included — control-plane
+ *  handlers/apiState.ts apiStateResponseField) and the shape `vxil push` READS
+ *  back instead of converging a second time (review 2026-09-23, finding 1: the
+ *  server's converge is the one that ran with the key's scopes; a client-side
+ *  repeat re-listed a KV-backed datum ~100 ms later and could double-create).
+ *  `ok:false` + `deferred:true` = the feature worker has not seen the config
+ *  yet (the client may converge after its own wait); `ok:false` otherwise =
+ *  a DEFINITE, named refusal (nothing to retry); `note` = converged nothing on
+ *  purpose (a disabled feature). */
+export interface ApiStateResponseField extends ApiStateSummary {
+  ok: boolean;
+  dry_run?: boolean;
+  deferred?: boolean;
+  error?: string;
+  note?: string;
+}
+
+/** The note every executor reports for a DISABLED feature whose block still
+ *  declares rows: the declaration is kept in the manifest and nothing is
+ *  converged (a parked feature is not a propagation window — review finding 2). */
+export const API_STATE_DISABLED_NOTE = 'feature disabled — declaration kept, not converged';
+
+/** `GET /v1/rate-limits/policies` is a 100-row HARD cap with no cursor. A list
+ *  AT the cap is not a complete live set, so planning creates against it would
+ *  re-POST every declared name the cap hid (review finding 5). Both executors
+ *  refuse with this message instead. */
+export function rlPolicyListCapError(liveCount: number): string | null {
+  if (liveCount < RL_POLICY_LIST_CAP) return null;
+  return `the policy list is at its ${RL_POLICY_LIST_CAP}-row hard cap (no cursor) — the live set may be incomplete; delete undeclared policies before converging`;
+}
+export const RL_POLICY_LIST_CAP = 100;
+
+/** `+2 created · ~1 updated · =3 unchanged · 1 undeclared (left in place)` —
+ *  the one-line summary `vxil push` prints and the apply journal notes. */
+export function formatApiStateSummary(s: ApiStateSummary): string {
+  const parts: string[] = [];
+  if (s.created.length) parts.push(`+${s.created.length} created`);
+  if (s.updated.length) parts.push(`~${s.updated.length} updated`);
+  if (s.recreated.length) parts.push(`↻${s.recreated.length} recreated`);
+  parts.push(`=${s.unchanged.length} unchanged`);
+  if (s.deleted.length) parts.push(`-${s.deleted.length} deleted`);
+  if (s.undeclared.length) parts.push(`${s.undeclared.length} undeclared (left in place)`);
+  if (s.pending_destructive.length) parts.push(`${s.pending_destructive.length} destructive-shaped NOT applied (--allow-destructive)`);
+  if (s.ambiguous.length) parts.push(`${s.ambiguous.length} ambiguous (duplicate live rows — not touched)`);
+  if (s.failed.length) parts.push(`${s.failed.length} failed`);
+  return parts.join(' · ');
+}
+
+/** The multi-line detail under the summary: one line per named row. */
+export function formatApiStateDetail(s: ApiStateSummary): string[] {
+  const lines: string[] = [];
+  for (const k of s.created) lines.push(`  + ${k}`);
+  for (const k of s.updated) lines.push(`  ~ ${k}`);
+  for (const k of s.recreated) lines.push(`  ↻ ${k} (recreated — new id)`);
+  for (const k of s.deleted) lines.push(`  - ${k} (deleted: undeclared, --allow-destructive)`);
+  for (const k of s.undeclared) lines.push(`  · ${k} — live but not declared (left in place; --allow-destructive deletes it)`);
+  for (const k of s.pending_destructive) lines.push(`  ! ${k} — needs delete+recreate (new id); re-run with --allow-destructive`);
+  for (const k of s.ambiguous) lines.push(`  ! ${k} — more than one live row carries this name; delete the extras first`);
+  for (const f of s.failed) lines.push(`  ✗ ${f.key} — ${f.error}`);
+  return lines;
+}