@homeflare/alchemy 0.38.0 → 0.40.0

package/src/telemetry/redact.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Pure-function coverage for `redactAttribute`/`wrapTracer`. layer.test.ts covers the same policy
+ * end to end, through a real `HttpClient` call and a real OTLP export — this file is the fast,
+ * exhaustive sweep of the redaction rules themselves.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Option from 'effect/Option';
+import type * as Tracer from 'effect/Tracer';
+import { DROP, REDACTED, redactAttribute, wrapTracer } from './redact.ts';
+
+describe('redactAttribute', () => {
+  test('drops every header attribute outright, request or response, regardless of value', () => {
+    expect(redactAttribute('http.request.header.authorization', 'Bearer x', {})).toBe(DROP);
+    expect(redactAttribute('http.request.header.x-api-key', 'k', {})).toBe(DROP);
+    expect(redactAttribute('http.response.header.set-cookie', 'a=b', {})).toBe(DROP);
+  });
+
+  test('drops url.query outright — no per-parameter allowlist', () => {
+    expect(redactAttribute('url.query', 'token=SECRET&safe=1', {})).toBe(DROP);
+  });
+
+  test('strips the query string and hash from url.full even with an empty policy', () => {
+    expect(redactAttribute('url.full', 'http://host/path?token=SECRET#frag', {})).toBe(
+      'http://host/path',
+    );
+  });
+
+  test('leaves url.full, url.path and server.address untouched when nothing matches the denylist', () => {
+    expect(redactAttribute('url.full', 'http://host:9428/insert/opentelemetry/v1/traces', {})).toBe(
+      'http://host:9428/insert/opentelemetry/v1/traces',
+    );
+    expect(redactAttribute('url.path', '/insert/opentelemetry/v1/traces', {})).toBe(
+      '/insert/opentelemetry/v1/traces',
+    );
+    expect(redactAttribute('server.address', 'http://host:9428', {})).toBe('http://host:9428');
+  });
+
+  test('blanks a denylisted path segment, exact match only — no substring match', () => {
+    const policy = { denylist: ['console-abc123'] };
+    expect(redactAttribute('url.path', '/proxy/network/console-abc123/site', policy)).toBe(
+      `/proxy/network/${REDACTED}/site`,
+    );
+    // "console-abc123-extra" must NOT match the denylisted "console-abc123" segment.
+    expect(redactAttribute('url.path', '/proxy/console-abc123-extra', policy)).toBe(
+      '/proxy/console-abc123-extra',
+    );
+  });
+
+  test('blanks a denylisted host in both url.full and server.address', () => {
+    const policy = { denylist: ['private.example.test'] };
+    expect(redactAttribute('server.address', 'https://private.example.test:443', policy)).toBe(
+      REDACTED,
+    );
+    expect(redactAttribute('url.full', 'https://private.example.test/api/site/x?y=1', policy)).toBe(
+      `https://${REDACTED}/api/site/x`,
+    );
+  });
+
+  test('a non-string value (e.g. server.port) and an unrecognized key pass through untouched', () => {
+    expect(redactAttribute('server.port', 8428, { denylist: ['8428'] })).toBe(8428);
+    expect(redactAttribute('alchemy.resource.fqn', 'stack/thing', { denylist: ['thing'] })).toBe(
+      'stack/thing',
+    );
+  });
+
+  test('a url.full value that fails to parse as a URL is left verbatim, not guessed at', () => {
+    expect(redactAttribute('url.full', 'not a url', { denylist: ['not'] })).toBe('not a url');
+  });
+});
+
+const testSpanOptions = {
+  annotations: undefined as never,
+  kind: 'internal' as const,
+  links: [],
+  name: 'test',
+  parent: Option.none(),
+  root: true,
+  sampled: true,
+  startTime: 0n,
+};
+
+const recordingInner = (): { calls: Array<[string, unknown]>; tracer: Tracer.Tracer } => {
+  const calls: Array<[string, unknown]> = [];
+  const tracer: Tracer.Tracer = {
+    span: (options) => ({
+      _tag: 'Span',
+      addLinks: () => {},
+      annotations: options.annotations,
+      attribute: (key, value) => calls.push([key, value]),
+      attributes: new Map(),
+      end: () => {},
+      event: () => {},
+      kind: options.kind,
+      links: options.links,
+      name: options.name,
+      parent: options.parent,
+      sampled: options.sampled,
+      spanId: 'span-1',
+      status: { _tag: 'Started', startTime: options.startTime },
+      traceId: 'trace-1',
+    }),
+  };
+  return { calls, tracer };
+};
+
+describe('wrapTracer', () => {
+  test('forwards an allowed attribute and withholds a dropped one from the real span', () => {
+    const { calls, tracer } = recordingInner();
+    const wrapped = wrapTracer(tracer, {});
+    const span = wrapped.span(testSpanOptions);
+    span.attribute('http.request.header.cookie', 'secret');
+    span.attribute('alchemy.resource.fqn', 'stack/thing');
+    expect(calls).toEqual([['alchemy.resource.fqn', 'stack/thing']]);
+  });
+
+  test("passes the span's identity and lifecycle through unchanged", () => {
+    const { tracer } = recordingInner();
+    const wrapped = wrapTracer(tracer, {});
+    const span = wrapped.span(testSpanOptions);
+    expect(span.name).toBe('test');
+    expect(span.spanId).toBe('span-1');
+    expect(span.traceId).toBe('trace-1');
+  });
+});

package/src/telemetry/redact.ts

@@ -0,0 +1,147 @@
+/**
+ * URL/header redaction for outgoing spans — applied at the `Tracer.Tracer` boundary so it holds for
+ * EVERY span source (a provider's own `Effect.withSpan`, effect's `HttpClient` client spans, and
+ * alchemy's own plan/apply/resource spans), not just the ones a caller remembers to annotate.
+ *
+ * ★ WHY THE TRACER, NOT AN HTTPCLIENT MIDDLEWARE. effect's `HttpClient.make` (src/unstable/http/
+ *   HttpClient.ts) hard-codes `span.attribute("url.full", …)`, `"url.query"` and
+ *   `http.request.header.<name>` on the span it creates — there is no hook to stop it recording
+ *   them. The one seam every span (HttpClient's included) passes through is `Tracer.span()`
+ *   returning a `Tracer.Span`, so `wrapTracer` intercepts `Span.attribute()` there instead.
+ * ⛔ NEVER RECORD HEADERS. A header NAME can itself be sensitive (`x-api-key`, a session cookie
+ *   name), so every `http.{request,response}.header.*` key is DROPPED, not value-redacted.
+ * ⚠️ QUERY STRINGS ARE STRIPPED WHOLE, not redacted per-parameter: an allowlist of "safe" params
+ *   would silently leak the next secret param a provider adds. `url.query` is dropped outright and
+ *   `url.full`/`url.path` never carry a `?…` past this point.
+ */
+import type * as Tracer from 'effect/Tracer';
+
+/** Host or path segments to blank wherever they appear in a URL attribute — exact-segment match. */
+export interface RedactionPolicy {
+  /**
+   * e.g. a UniFi console id embedded in a path (`/proxy/network/api/site/<id>/...`) or a private
+   * hostname a consumer never wants leaving its own process. Compared against the full hostname and
+   * against each `/`-separated path segment — never a substring match, so `"db"` cannot accidentally
+   * blank `"db1.example.test"`.
+   */
+  readonly denylist?: ReadonlyArray<string>;
+}
+
+export const REDACTED = '<redacted>';
+
+/** Returned by `redactAttribute` to mean "drop this attribute entirely — do not forward it". */
+export const DROP: unique symbol = Symbol.for('homeflare/alchemy/telemetry/drop-attribute');
+
+const HEADER_ATTRIBUTE = /^http\.(?:request|response)\.header\./;
+
+const redactSegments = (value: string, denylist: ReadonlySet<string>): string =>
+  value
+    .split('/')
+    .map((segment) => (denylist.has(segment) ? REDACTED : segment))
+    .join('/');
+
+/**
+ * Applies `policy` to one span attribute. Returns `DROP` when the key must never be recorded at
+ * all (every header); otherwise returns the value to record, with URLs stripped of their query
+ * string and hash and their denylisted host/path segments blanked. A value this function does not
+ * recognize (not a URL-shaped key, or not a string) passes through unchanged — alchemy's own
+ * engine attributes (`resource.fqn`, `plan.action`, …) are never URLs and are never touched.
+ */
+export const redactAttribute = (key: string, value: unknown, policy: RedactionPolicy): unknown => {
+  if (HEADER_ATTRIBUTE.test(key)) return DROP;
+  if (key === 'url.query') return DROP;
+  if (typeof value !== 'string') return value;
+  const denylist = new Set(policy.denylist ?? []);
+  if (denylist.size === 0 && key !== 'url.full' && key !== 'server.address') return value;
+  // ⚠️ MEASURED 2026-09-26 (docs/telemetry-spike.md): effect's own `HttpClient.make` sets
+  //   `server.address` to `url.origin` (`http://host:port`), NOT a bare hostname — a denylist entry
+  //   naming just a hostname would never match the raw value, so this parses it out the same way
+  //   `url.full` does.
+  // ⛔ FIX (redteam PR 302 MINOR item 5, 2026-09-26): the OTel semantic convention's own default for
+  //   `server.address` IS a bare hostname with no scheme (`new URL(value)` throws on that), and other
+  //   instrumentation could emit exactly that even though effect's `HttpClient` doesn't today —
+  //   `redactAttribute('server.address', 'db1.example.test', { denylist: ['db1.example.test'] })`
+  //   returned the value verbatim before this fallback. Compare the raw string directly when it
+  //   isn't a parseable URL, instead of giving up.
+  if (key === 'server.address') {
+    try {
+      const url = new URL(value);
+      return denylist.has(url.hostname) ? REDACTED : value;
+    } catch {
+      return denylist.has(value) ? REDACTED : value;
+    }
+  }
+  if (key === 'url.path') return redactSegments(value, denylist);
+  if (key === 'url.full') {
+    try {
+      const url = new URL(value);
+      const host = denylist.has(url.hostname) ? REDACTED : url.host;
+      return `${url.protocol}//${host}${redactSegments(url.pathname, denylist)}`;
+    } catch {
+      // Not a URL we can parse (a relative path effect couldn't resolve) — leave it verbatim
+      // rather than guess; `url.full` is the one HttpClient always sets from a resolved `URL`, so
+      // this branch is a defensive fallback, not the expected path.
+      return value;
+    }
+  }
+  return value;
+};
+
+const redactAttributes = (
+  attributes: Record<string, unknown>,
+  policy: RedactionPolicy,
+): Record<string, unknown> => {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(attributes)) {
+    const redacted = redactAttribute(key, value, policy);
+    if (redacted !== DROP) out[key] = redacted;
+  }
+  return out;
+};
+
+/**
+ * Wraps a `Tracer.Tracer` so every span it creates redacts its attributes and event attributes
+ * through `redactAttribute`/`redactAttributes` before they reach the real span (and therefore
+ * before OTLP serialization ever sees them). Everything else — timing, status, links, the span's
+ * own identity — passes straight through to `inner`.
+ */
+export const wrapTracer = (inner: Tracer.Tracer, policy: RedactionPolicy): Tracer.Tracer => ({
+  context: inner.context,
+  span(options): Tracer.Span {
+    const real = inner.span(options);
+    return {
+      _tag: 'Span',
+      spanId: real.spanId,
+      traceId: real.traceId,
+      parent: real.parent,
+      annotations: real.annotations,
+      get name() {
+        return real.name;
+      },
+      get status() {
+        return real.status;
+      },
+      get attributes() {
+        return real.attributes;
+      },
+      get links() {
+        return real.links;
+      },
+      sampled: real.sampled,
+      kind: real.kind,
+      end: (endTime, exit) => {
+        real.end(endTime, exit);
+      },
+      attribute: (key, value) => {
+        const redacted = redactAttribute(key, value, policy);
+        if (redacted !== DROP) real.attribute(key, redacted);
+      },
+      event: (name, startTime, attributes) => {
+        real.event(name, startTime, attributes ? redactAttributes(attributes, policy) : attributes);
+      },
+      addLinks: (links) => {
+        real.addLinks(links);
+      },
+    };
+  },
+});

package/src/unifi/acl-rule-drift.ts

@@ -0,0 +1,57 @@
+/**
+ * `Unifi.AclRule`'s `matches` AND `driftOf` (B6) — both built on the ONE field list below, the
+ * same `fieldDrift`-is-the-only-comparison shape `network-drift.ts`'s header explains (MEDIUM-4,
+ * red team, 2026-09-26): `matches(attrs, props) === (driftOf(live, props).length === 0)` is true
+ * BY CONSTRUCTION.
+ *
+ * ⚠️ `stripNullish: true` ON EVERY FIELD BY DEFAULT (`drift.ts`'s `defaultEqual`) — same "UniFi's
+ *   JSON answers `null`, a declaration omits" tolerance `network-drift.ts` documents.
+ * ⛔ `enforcingDeviceFilter`/`protocolFilter` RUN THROUGH `acl-rule-form.ts`'s normalizers on BOTH
+ *   sides before comparing — never applied to only `live` or only `declared` (that specific gap is
+ *   what MEDIUM-4's own mutant found in `network-drift.ts`; see its header).
+ */
+import type * as aclRules from '@distilled.cloud/unifi-network/access_control_acl_rules';
+import { makeDriftOf } from './drift.ts';
+import {
+  type AclRuleAttributes,
+  type AclRuleProps,
+  attributesOf,
+  normalizeDeviceFilter,
+  normalizeProtocolFilter,
+} from './acl-rule-form.ts';
+
+const fieldDrift = makeDriftOf<AclRuleAttributes, AclRuleProps>([
+  { field: 'action', live: (a) => a.action, declared: (p) => p.action },
+  { field: 'description', live: (a) => a.description, declared: (p) => p.description },
+  {
+    field: 'destinationFilter',
+    live: (a) => a.destinationFilter,
+    declared: (p) => p.destinationFilter,
+  },
+  { field: 'enabled', live: (a) => a.enabled, declared: (p) => p.enabled },
+  {
+    field: 'enforcingDeviceFilter',
+    live: (a) => normalizeDeviceFilter(a.enforcingDeviceFilter),
+    declared: (p) => normalizeDeviceFilter(p.enforcingDeviceFilter),
+  },
+  { field: 'name', live: (a) => a.name, declared: (p) => p.name },
+  { field: 'sourceFilter', live: (a) => a.sourceFilter, declared: (p) => p.sourceFilter },
+  { field: 'type', live: (a) => a.type, declared: (p) => p.type },
+  {
+    field: 'protocolFilter',
+    live: (a) => normalizeProtocolFilter(a.protocolFilter),
+    declared: (p) => normalizeProtocolFilter(p.protocolFilter),
+  },
+  { field: 'networkIdFilter', live: (a) => a.networkIdFilter, declared: (p) => p.networkIdFilter },
+]);
+
+export const matches = (attributes: AclRuleAttributes, props: AclRuleProps): boolean =>
+  fieldDrift(attributes, props).length === 0;
+
+/**
+ * Per-field live-vs-declared drift straight from one live read — the task's own API
+ * (`driftOf(live, props)`), so `homeflare-network`'s pre-import drift check never has to derive
+ * `attributesOf` itself just to call this.
+ */
+export const driftOf = (live: aclRules.ACLRule, props: AclRuleProps) =>
+  fieldDrift(attributesOf(live, props), props);

package/src/unifi/acl-rule-form.ts

@@ -0,0 +1,135 @@
+/**
+ * `Unifi.AclRule`'s wire shape — the declarable subset of `ACLRule` (`getAclRule`'s own decode
+ *   target — `ACLRuleObject` is the structurally-identical page-list item type, unused here), and
+ *   how a live read
+ * becomes both plan attributes and a rendered declaration. Rule ORDER is a separate resource
+ * (`acl-rule-ordering.ts`, T5) — this file is one rule's own fields only.
+ *
+ * ⚠️ `sourceFilter`/`destinationFilter` STAY `unknown`, ON THE SDK'S OWN AUTHORITY.
+ *   `access_control_acl_rules.ts`'s own comment on both ("Shape varies by variant — widened by
+ *   scripts/convert.ts; see README") says the OpenAPI discriminator these vary over was flattened
+ *   at generation time (T10), same as `network-form.ts`'s `ipv4Configuration`. A3 (typing these
+ *   per-discriminator) is scoped OUT of this PR — see the plan's family inventory — so both stay
+ *   opaque JSON, compared with plain `deepEqual`, honest about not being decoded.
+ *
+ * ⚠️ KNOWN GAP UNTIL A3 (T15, red team, Minor finding 4): the vendor's own variant DTOs for these
+ *   filters carry SET-LIKE arrays too (`networkIds`, `ipAddressesOrSubnets`, `portFilter`,
+ *   `macAddresses` — `docs/unifi-acl-rule.md`'s own field notes). Because the filter stays opaque,
+ *   `deepEqual` compares those nested arrays order-sensitively, the same false-`update` risk this
+ *   file already removes for `deviceIds`/`protocolFilter` by normalizing them — but here there is
+ *   no decoded field to normalize. Accepted as a known gap, not fixed, until A3 types the filter
+ *   per-discriminator and can apply `sortedSet` to its own array fields.
+ *
+ * ⛔ `index` IS ATTRIBUTES-ONLY, NEVER DECLARED. `CreateAclRuleRequest`'s own field comment:
+ *   "ACL rule index. This property is deprecated and has no effect. Use the dedicated ACL rule
+ *   reordering endpoint." The live object's current position is `acl-rule-ordering.ts`'s concern
+ *   (`ACLRuleOrdering.orderedAclRuleIds`), not this resource's declared identity — reporting it
+ *   here without comparing it avoids a field that can never converge under this family's own
+ *   `matches` (nothing here could ever change it) from silently pretending to be declarable.
+ *
+ * ⛔ `enforcingDeviceFilter.deviceIds` AND `protocolFilter` ARE SETS, NOT SEQUENCES — same
+ *   reasoning `firewall-zone-form.ts` gives for `networkIds`: "IDs of the Switch-capable devices
+ *   used to enforce the ACL rule" and "Protocols this ACL rule will be applied to" both describe
+ *   membership, with no indication either list is ordered like `acl-rule-ordering.ts`'s rule-id
+ *   sequence. Left alone, a console that returns either in a different order between calls would
+ *   plan a spurious `update` that this read-only family's `reconcile` then refuses forever.
+ */
+import type * as aclRules from '@distilled.cloud/unifi-network/access_control_acl_rules';
+
+const sortedSet = (values: readonly string[]): string[] => [...new Set(values)].sort();
+
+/** ★ EXPORTED so `acl-rule-drift.ts` normalizes both live and declared sides identically — see
+ *  `network-form.ts`'s own header for why a normalizer applied to only one side is a bug class. */
+export const normalizeDeviceFilter = (
+  value: aclRules.ACLRuleDeviceFilter | undefined,
+): aclRules.ACLRuleDeviceFilter | undefined =>
+  value == null
+    ? value
+    : {
+        ...value,
+        ...(value.deviceIds !== undefined ? { deviceIds: sortedSet(value.deviceIds) } : {}),
+      };
+
+export const normalizeProtocolFilter = (
+  value: readonly string[] | undefined,
+): string[] | undefined => (value == null ? undefined : sortedSet(value));
+
+/** ⚠️ EVERY OPTIONAL FIELD SPELLS OUT `| undefined` — `exactOptionalPropertyTypes`; see
+ *  `network-form.ts`'s own header. */
+export interface AclRuleProps {
+  siteId: string;
+  aclRuleId: string;
+  /** `ALLOW` or `BLOCK` (also accepts a future vendor value the spec did not enumerate). */
+  action: string;
+  description?: string | undefined;
+  /** Traffic destination filter — opaque, see the header. */
+  destinationFilter?: unknown;
+  enabled: boolean;
+  /** Devices enforcing this rule — compared as a SET, see the header. */
+  enforcingDeviceFilter?: aclRules.ACLRuleDeviceFilter | undefined;
+  name: string;
+  /** Traffic source filter — opaque, see the header. */
+  sourceFilter?: unknown;
+  type: string;
+  /** Protocols this rule applies to — compared as a SET, see the header. */
+  protocolFilter?: string[] | undefined;
+  networkIdFilter?: string | undefined;
+}
+
+export interface AclRuleAttributes {
+  siteId: string;
+  aclRuleId: string;
+  action: string;
+  description: string | undefined;
+  destinationFilter: unknown;
+  enabled: boolean;
+  enforcingDeviceFilter: aclRules.ACLRuleDeviceFilter | undefined;
+  /** ACL rule index (current priority position) — server-derived, never declared; see header. */
+  index: number;
+  name: string;
+  sourceFilter: unknown;
+  type: string;
+  protocolFilter: string[] | undefined;
+  networkIdFilter: string | undefined;
+  /** `metadata.origin` — server-derived, never declared; see `firewall-zone-form.ts`'s own. */
+  metadataOrigin: string;
+}
+
+export const attributesOf = (live: aclRules.ACLRule, props: AclRuleProps): AclRuleAttributes => ({
+  siteId: props.siteId,
+  aclRuleId: live.id,
+  action: live.action,
+  description: live.description,
+  destinationFilter: live.destinationFilter,
+  enabled: live.enabled,
+  enforcingDeviceFilter: normalizeDeviceFilter(live.enforcingDeviceFilter),
+  index: live.index,
+  name: live.name,
+  sourceFilter: live.sourceFilter,
+  type: live.type,
+  protocolFilter: normalizeProtocolFilter(live.protocolFilter),
+  networkIdFilter: live.networkIdFilter,
+  metadataOrigin: live.metadata.origin,
+});
+
+/**
+ * The declaration renderer (task spec: "given one live object, return the props a declaration
+ * needs so its plan is noop"). A later import script feeds `getAclRule`'s own response straight in
+ * and writes the result as `aclRule('<id>', declareAclRule(live, siteId))` — no field is invented
+ * or defaulted beyond what `attributesOf` already reports, so `matches(attributesOf(live, props),
+ * declareAclRule(live, siteId))` is `true` by construction (`acl-rule.test.ts` proves it).
+ */
+export const declareAclRule = (live: aclRules.ACLRule, siteId: string): AclRuleProps => ({
+  siteId,
+  aclRuleId: live.id,
+  action: live.action,
+  description: live.description,
+  destinationFilter: live.destinationFilter,
+  enabled: live.enabled,
+  enforcingDeviceFilter: normalizeDeviceFilter(live.enforcingDeviceFilter),
+  name: live.name,
+  sourceFilter: live.sourceFilter,
+  type: live.type,
+  protocolFilter: normalizeProtocolFilter(live.protocolFilter),
+  networkIdFilter: live.networkIdFilter,
+});

package/src/unifi/acl-rule-ordering-form.ts

@@ -0,0 +1,79 @@
+/**
+ * `Unifi.AclRuleOrdering`'s wire shape — ONE resource per site (`getAclRuleOrdering`'s own scope,
+ * `GET /v1/sites/{siteId}/acl-rules/ordering`), not per rule. Compare with `firewall-zone-form.ts`'s
+ * `networkIds`, which is a genuine SET: this file's `orderedAclRuleIds` is the opposite case.
+ *
+ * ⛔ T5 — `orderedAclRuleIds` IS A SEQUENCE, NEVER RUN THROUGH `sortedSet`. The endpoint's own name
+ *   (`updateAclRuleOrdering`) and its field's own vendor comment on `ACLRule.index` ("Lower index
+ *   has higher priority") both say this list's POSITION is the entire value it carries — rule
+ *   priority. `firewall-zone-form.ts`'s `sortedSet`/`network-form.ts`'s three set normalizers all
+ *   exist to stop the OPPOSITE mistake (treating a set as if order mattered); applying the same
+ *   fix here would silently discard the one thing this resource represents. `drift.ts`'s
+ *   `defaultEqual` (`deepEqual`) already compares arrays element-by-element without sorting them
+ *   (its header: "sorts object KEYS but NOT ARRAY ELEMENTS") — so leaving this field un-normalized
+ *   is what makes the comparison order-sensitive, not an oversight to "fix" later.
+ *
+ * ★ `makeDriftOf` (`drift.ts`), NO CUSTOM `equal` — same framework every other family's
+ *   `matches`/`driftOf` share (MEDIUM-4). Its default `deepEqual` is ALREADY order-sensitive for
+ *   arrays (see the paragraph above), so the absence of a custom `equal` here, unlike
+ *   `firewall-zone-form.ts`'s `networkIds` entry, is itself the "never sortedSet" rule in force —
+ *   not an oversight.
+ */
+import type * as aclRules from '@distilled.cloud/unifi-network/access_control_acl_rules';
+import { makeDriftOf } from './drift.ts';
+
+export interface AclRuleOrderingProps {
+  siteId: string;
+  /** Rule IDs in priority order, highest priority first — never compared as a set (see header). */
+  orderedAclRuleIds: string[];
+}
+
+export interface AclRuleOrderingAttributes {
+  siteId: string;
+  orderedAclRuleIds: string[];
+}
+
+export const attributesOf = (
+  live: aclRules.ACLRuleOrdering,
+  props: AclRuleOrderingProps,
+): AclRuleOrderingAttributes => ({
+  siteId: props.siteId,
+  orderedAclRuleIds: live.orderedAclRuleIds,
+});
+
+/**
+ * The declaration renderer (task spec: "given one live object, return the props a declaration
+ * needs so its plan is noop"). A later import script feeds `getAclRuleOrdering`'s own response
+ * straight in and writes the result as `aclRuleOrdering('site-1', declareAclRuleOrdering(live,
+ * siteId))` — `matches(attributesOf(live, props), declareAclRuleOrdering(live, siteId))` is `true`
+ * by construction (`acl-rule-ordering.test.ts` proves it).
+ */
+export const declareAclRuleOrdering = (
+  live: aclRules.ACLRuleOrdering,
+  siteId: string,
+): AclRuleOrderingProps => ({
+  siteId,
+  orderedAclRuleIds: live.orderedAclRuleIds,
+});
+
+const fieldDrift = makeDriftOf<AclRuleOrderingAttributes, AclRuleOrderingProps>([
+  {
+    field: 'orderedAclRuleIds',
+    live: (a) => a.orderedAclRuleIds,
+    declared: (p) => p.orderedAclRuleIds,
+  },
+]);
+
+export const matches = (
+  attributes: AclRuleOrderingAttributes,
+  props: AclRuleOrderingProps,
+): boolean => fieldDrift(attributes, props).length === 0;
+
+/**
+ * Per-field live-vs-declared drift straight from one live read — the task's own API
+ * (`driftOf(live, props)`). Only one field exists, so this either reports nothing or the whole
+ * ordered pair, never a per-position breakdown -- a future consumer wanting "which rule moved"
+ * would need to diff the two arrays itself.
+ */
+export const driftOf = (live: aclRules.ACLRuleOrdering, props: AclRuleOrderingProps) =>
+  fieldDrift(attributesOf(live, props), props);