sap-ai-dev-toolkit 0.9.9918 → 0.9.9921

package/src/iflow-bundle.mjs

@@ -2,11 +2,29 @@
 // Pure: no network. Manifest import headers follow FlashPipe's tenant-verified
 // test artifact (Apache-2.0, see NOTICE).
 import { readFileSync } from 'node:fs';
-import { strFromU8, strToU8, unzipSync, zipSync } from 'fflate';
+import { createHash } from 'node:crypto';
+import { strFromU8, strToU8, Unzip, UnzipInflate, Zip, ZipDeflate } from 'fflate';
 import { IntegrationError } from './integration-http.mjs';
 
 export const IFLOW_TEMPLATES = Object.freeze(['https-request-reply-http']);
 
+/** Content identity independent of ZIP ordering, compression and timestamps. */
+export function bundleDigest(files) {
+  const hash = createHash('sha256');
+  const entries = [...files].map(([path, bytes]) => [Buffer.from(path, 'utf8'), bytes]);
+  entries.sort(([a], [b]) => Buffer.compare(a, b));
+  const length = Buffer.allocUnsafe(4);
+  for (const [path, bytes] of entries) {
+    for (const value of [path, bytes]) {
+      if (value.byteLength > 0xffffffff) throw new IntegrationError('Bundle member exceeds digest length limit');
+      length.writeUInt32BE(value.byteLength);
+      hash.update(length);
+      hash.update(value);
+    }
+  }
+  return hash.digest('hex');
+}
+
 const IMPORT_PACKAGE = "com.sap.esb.application.services.cxf.interceptor,com.sap.esb.security,com.sap.it.op.agent.api,com.sap.it.op.agent.collector.camel,com.sap.it.op.agent.collector.cxf,com.sap.it.op.agent.mpl,javax.jms,javax.jws,javax.wsdl,javax.xml.bind.annotation,javax.xml.namespace,javax.xml.ws,org.apache.camel;version=\"2.8\",org.apache.camel.builder;version=\"2.8\",org.apache.camel.builder.xml;version=\"2.8\",org.apache.camel.component.cxf,org.apache.camel.model;version=\"2.8\",org.apache.camel.processor;version=\"2.8\",org.apache.camel.processor.aggregate;version=\"2.8\",org.apache.camel.spring.spi;version=\"2.8\",org.apache.commons.logging,org.apache.cxf.binding,org.apache.cxf.binding.soap,org.apache.cxf.binding.soap.spring,org.apache.cxf.bus,org.apache.cxf.bus.resource,org.apache.cxf.bus.spring,org.apache.cxf.buslifecycle,org.apache.cxf.catalog,org.apache.cxf.configuration.jsse;version=\"2.5\",org.apache.cxf.configuration.spring,org.apache.cxf.endpoint,org.apache.cxf.headers,org.apache.cxf.interceptor,org.apache.cxf.management.counters;version=\"2.5\",org.apache.cxf.message,org.apache.cxf.phase,org.apache.cxf.resource,org.apache.cxf.service.factory,org.apache.cxf.service.model,org.apache.cxf.transport,org.apache.cxf.transport.common.gzip,org.apache.cxf.transport.http,org.apache.cxf.transport.http.policy,org.apache.cxf.workqueue,org.apache.cxf.ws.rm.persistence,org.apache.cxf.wsdl11,org.osgi.framework;version=\"1.6.0\",org.slf4j;version=\"1.6\",org.springframework.beans.factory.config;version=\"3.0\",com.sap.esb.camel.security.cms,org.apache.camel.spi,com.sap.esb.webservice.audit.log,com.sap.esb.camel.endpoint.configurator.api,com.sap.esb.camel.jdbc.idempotency.reorg,javax.sql,org.apache.camel.processor.idempotent.jdbc,org.osgi.service.blueprint;version=\"[1.0.0,2.0.0)\"";
 const IMPORT_SERVICE = "com.sap.esb.webservice.audit.log.AuditLogger,com.sap.esb.security.KeyManagerFactory;multiple:=false,com.sap.esb.security.TrustManagerFactory;multiple:=false,javax.sql.DataSource;multiple:=false;filter=\"(dataSourceName=default)\",org.apache.cxf.ws.rm.persistence.RMStore;multiple:=false,com.sap.esb.camel.security.cms.SignatureSplitter;multiple:=false";
 
@@ -263,20 +281,290 @@ export function buildIflowBundle({
     files[PARAMETERS_PROP] = strToU8(propertiesText(merged));
     files[PARAMETERS_PROPDEF] = strToU8(propdefText(parameterEntries.map(([key]) => key)));
   }
-  return zipSync(files);
+  return writeBundle(Object.entries(files));
+}
+
+const MAX_ARCHIVE_BYTES = 20 * 1024 * 1024;
+const MAX_MEMBER_BYTES = 20 * 1024 * 1024;
+const MAX_EXPANDED_BYTES = 100 * 1024 * 1024;
+const MAX_MEMBERS = 2000;
+// Limit each inflate call, not just its accumulated output. A small compressed
+// chunk bounds fflate's temporary output even when the declared size is false.
+const INFLATE_CHUNK_BYTES = 1024;
+const ZIP_CHUNK_BYTES = 64 * 1024;
+const EMPTY_BYTES = new Uint8Array(0);
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+function archiveError(message) {
+  return new IntegrationError(`iFlow bundle zip: ${message}`);
+}
+
+function validateMemberPath(path, seen) {
+  if (typeof path !== 'string' || !path || path.includes('\0') || path.includes('\\')
+    || path.startsWith('/') || /^[A-Za-z]:/.test(path)
+    || Buffer.byteLength(path, 'utf8') > 65535 || strFromU8(strToU8(path)) !== path) {
+    throw archiveError('unsafe member path');
+  }
+  const segments = path.endsWith('/') ? path.slice(0, -1).split('/') : path.split('/');
+  if (segments.some(part => !part || part === '.' || part === '..')) throw archiveError('unsafe member path');
+  if (seen.has(path)) throw archiveError('duplicate member path');
+  seen.add(path);
+  if (seen.size > MAX_MEMBERS) throw archiveError(`more than ${MAX_MEMBERS} members`);
+}
+
+function validatePathRelationships(paths) {
+  for (const path of paths) {
+    if (path.endsWith('/') && paths.has(path.slice(0, -1))) throw archiveError('conflicting member paths');
+    for (let slash = path.indexOf('/'); slash >= 0; slash = path.indexOf('/', slash + 1)) {
+      if (paths.has(path.slice(0, slash))) throw archiveError('file used as a member directory');
+    }
+  }
+}
+
+function checkExtraFields(bytes, start, length) {
+  const end = start + length;
+  while (start < end) {
+    if (start + 4 > end) throw archiveError('malformed extra field');
+    const kind = bytes[start] | (bytes[start + 1] << 8);
+    const size = bytes[start + 2] | (bytes[start + 3] << 8);
+    start += 4 + size;
+    if (start > end) throw archiveError('truncated extra field');
+    // Neither ZIP64 nor an alternate Unicode filename is needed for bounded
+    // content bundles. Reject rather than letting another importer choose a
+    // different size, offset or path than the one checked here.
+    if (kind === 1 || kind === 0x7075) throw archiveError('unsupported ZIP64 or alternate filename metadata');
+  }
+}
+
+/** Check archive structure without trusting its expanded-size declarations. */
+function inspectArchive(bytes) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const u16 = offset => view.getUint16(offset, true);
+  const u32 = offset => view.getUint32(offset, true);
+  let end = -1;
+  for (let offset = bytes.length - 22; offset >= Math.max(0, bytes.length - 65557); offset -= 1) {
+    if (u32(offset) === 0x06054b50 && offset + 22 + u16(offset + 20) === bytes.length) {
+      end = offset;
+      break;
+    }
+  }
+  if (end < 0) throw archiveError('missing or truncated end record');
+  const count = u16(end + 10);
+  const centralSize = u32(end + 12);
+  const centralOffset = u32(end + 16);
+  if (u16(end + 4) || u16(end + 6) || u16(end + 8) !== count
+    || count > MAX_MEMBERS || centralOffset + centralSize !== end) {
+    throw archiveError('invalid, split or oversized central directory');
+  }
+  const entries = [];
+  const names = new Set();
+  let offset = centralOffset;
+  for (let index = 0; index < count; index += 1) {
+    if (offset + 46 > end || u32(offset) !== 0x02014b50) throw archiveError('malformed central directory');
+    const flags = u16(offset + 8);
+    const compression = u16(offset + 10);
+    const crc = u32(offset + 16);
+    const compressedSize = u32(offset + 20);
+    const originalSize = u32(offset + 24);
+    const nameLength = u16(offset + 28);
+    const extraLength = u16(offset + 30);
+    const commentLength = u16(offset + 32);
+    const localOffset = u32(offset + 42);
+    const next = offset + 46 + nameLength + extraLength + commentLength;
+    if (next > end || u16(offset + 34) || (flags & ~0x080e) || ![0, 8].includes(compression)
+      || (compression === 0 && (flags & 6)) || compressedSize > MAX_ARCHIVE_BYTES
+      || (compression === 8 && compressedSize < 2)
+      || originalSize > MAX_MEMBER_BYTES || localOffset >= centralOffset) {
+      throw archiveError('unsupported or oversized member');
+    }
+    const nameBytes = bytes.subarray(offset + 46, offset + 46 + nameLength);
+    const name = flags & 0x0800 ? utf8Decoder.decode(nameBytes) : strFromU8(nameBytes, true);
+    validateMemberPath(name, names);
+    checkExtraFields(bytes, offset + 46 + nameLength, extraLength);
+    entries.push({ name, nameBytes, flags, compression, crc, compressedSize, originalSize, localOffset });
+    offset = next;
+  }
+  if (offset !== end) throw archiveError('central directory length mismatch');
+  validatePathRelationships(names);
+  entries.sort((a, b) => a.localOffset - b.localOffset);
+  offset = 0;
+  for (const entry of entries) {
+    const { localOffset, nameBytes, flags, compression, crc, compressedSize, originalSize } = entry;
+    if (localOffset !== offset || offset + 30 > centralOffset || u32(offset) !== 0x04034b50) {
+      throw archiveError('missing, overlapping or unindexed local member');
+    }
+    const nameLength = u16(offset + 26);
+    const extraLength = u16(offset + 28);
+    const dataOffset = offset + 30 + nameLength + extraLength;
+    if (dataOffset + compressedSize > centralOffset || flags !== u16(offset + 6)
+      || compression !== u16(offset + 8) || nameLength !== nameBytes.length) {
+      throw archiveError('local and central member mismatch');
+    }
+    for (let index = 0; index < nameLength; index += 1) {
+      if (bytes[offset + 30 + index] !== nameBytes[index]) throw archiveError('local and central path mismatch');
+    }
+    checkExtraFields(bytes, offset + 30 + nameLength, extraLength);
+    for (const [field, expected] of [[14, crc], [18, compressedSize], [22, originalSize]]) {
+      const actual = u32(offset + field);
+      if (actual !== expected && (!(flags & 8) || actual !== 0)) throw archiveError('local member size or checksum mismatch');
+    }
+    entry.dataOffset = dataOffset;
+    offset = dataOffset + compressedSize;
+    if (flags & 8) {
+      // A signed or unsigned classic data descriptor must agree with the
+      // central record. Try both when a CRC happens to equal the signature.
+      const descriptor = [offset, offset + 4].find(start =>
+        (start === offset || (offset + 4 <= centralOffset && u32(offset) === 0x08074b50))
+        && start + 12 <= centralOffset && u32(start) === crc
+        && u32(start + 4) === compressedSize && u32(start + 8) === originalSize);
+      if (descriptor === undefined) throw archiveError('missing or invalid data descriptor');
+      offset = descriptor + 12;
+    }
+  }
+  if (offset !== centralOffset) throw archiveError('unindexed or truncated member data');
+  return { entries, centralOffset };
+}
+
+const crcTable = new Uint32Array(256);
+for (let index = 0; index < crcTable.length; index += 1) {
+  let value = index;
+  for (let bit = 0; bit < 8; bit += 1) value = (value >>> 1) ^ ((value & 1) ? 0xedb88320 : 0);
+  crcTable[index] = value;
+}
+
+function joinChunks(chunks, size) {
+  if (chunks.length === 1) return chunks[0];
+  const result = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return result;
 }
 
-/** Unzip a bundle into path → bytes. */
+/** Unzip a bounded, structurally checked bundle into path → exact bytes. */
 export function readBundle(bytes) {
+  if (!(bytes instanceof Uint8Array)) throw archiveError('archive must be bytes');
+  if (bytes.length > MAX_ARCHIVE_BYTES) throw archiveError('compressed archive exceeds 20 MiB');
+  let activeStream;
   try {
-    return new Map(Object.entries(unzipSync(bytes)));
-  } catch {
-    throw new IntegrationError('iFlow bundle is not a readable zip archive');
+    const { entries } = inspectArchive(bytes);
+    const files = new Map();
+    let total = 0;
+    let discovered = 0;
+    let completed = 0;
+    const unzip = new Unzip(file => {
+      if (activeStream) throw archiveError('incomplete preceding member');
+      activeStream = file;
+      const entry = entries[discovered++];
+      if (!entry || file.name !== entry.name) throw archiveError('unexpected streamed member');
+      const chunks = [];
+      let size = 0;
+      let crc = 0xffffffff;
+      file.ondata = (error, chunk, final) => {
+        if (error) throw error instanceof IntegrationError ? error : archiveError('invalid or truncated compressed member');
+        size += chunk.length;
+        total += chunk.length;
+        if (size > MAX_MEMBER_BYTES || total > MAX_EXPANDED_BYTES) throw archiveError('actual expanded byte limit exceeded');
+        if (size > entry.originalSize) throw archiveError('actual member size exceeds declared size');
+        for (const byte of chunk) crc = crcTable[(crc ^ byte) & 255] ^ (crc >>> 8);
+        if (chunk.length) chunks.push(chunk);
+        if (final) {
+          if (size !== entry.originalSize || ((crc ^ 0xffffffff) >>> 0) !== entry.crc) {
+            throw archiveError('member size or checksum mismatch');
+          }
+          if (entry.name.endsWith('/') && size) throw archiveError('nonempty directory member');
+          files.set(entry.name, joinChunks(chunks, size));
+          chunks.length = 0;
+          activeStream = undefined;
+          completed += 1;
+        }
+      };
+      file.start();
+    });
+    unzip.register(UnzipInflate);
+    const pushRange = (start, end) => {
+      for (let offset = start; offset < end; offset += INFLATE_CHUNK_BYTES) {
+        unzip.push(bytes.subarray(offset, Math.min(end, offset + INFLATE_CHUNK_BYTES)), false);
+      }
+    };
+    for (const entry of entries) {
+      if (entry.flags & 8) {
+        // Supply the already verified descriptor sizes to the streaming
+        // decoder. This prevents signature-like binary data from being
+        // mistaken for a descriptor, without copying the member payload.
+        const header = new Uint8Array(bytes.subarray(entry.localOffset, entry.localOffset + 30));
+        const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+        view.setUint16(6, entry.flags & ~8, true);
+        view.setUint32(14, entry.crc, true);
+        view.setUint32(18, entry.compressedSize, true);
+        view.setUint32(22, entry.originalSize, true);
+        unzip.push(header, false);
+        pushRange(entry.localOffset + 30, entry.dataOffset + entry.compressedSize);
+      } else {
+        pushRange(entry.localOffset, entry.dataOffset + entry.compressedSize);
+      }
+    }
+    // The central directory was checked above, not streamed as local records:
+    // arbitrary ZIP comments must never be scanned for apparent file headers.
+    // One sentinel byte also lets fflate discover a final zero-length member.
+    unzip.push(Uint8Array.of(0), true);
+    if (discovered !== entries.length || completed !== entries.length) throw archiveError('incomplete member streams');
+    return files;
+  } catch (error) {
+    activeStream?.terminate();
+    if (error instanceof IntegrationError) throw error;
+    throw archiveError('not a readable zip archive');
   }
 }
 
+/** Write only archives accepted by the same path, count and byte budgets. */
 export function writeBundle(files) {
-  return zipSync(Object.fromEntries(files));
+  const entries = [];
+  const names = new Set();
+  let expandedSize = 0;
+  for (const [name, bytes] of files) {
+    validateMemberPath(name, names);
+    if (!(bytes instanceof Uint8Array)) throw archiveError('member content must be bytes');
+    if (bytes.length > MAX_MEMBER_BYTES || (name.endsWith('/') && bytes.length)) throw archiveError('invalid member size');
+    expandedSize += bytes.length;
+    if (expandedSize > MAX_EXPANDED_BYTES) throw archiveError('actual expanded byte limit exceeded');
+    entries.push([name, bytes]);
+  }
+  validatePathRelationships(names);
+  const chunks = [];
+  let size = 0;
+  const zip = new Zip((error, chunk) => {
+    if (error) throw error instanceof IntegrationError ? error : archiveError('unable to write archive');
+    size += chunk.length;
+    if (size > MAX_ARCHIVE_BYTES) throw archiveError('compressed archive exceeds 20 MiB');
+    if (chunk.length) chunks.push(chunk);
+  });
+  try {
+    for (const [name, bytes] of entries) {
+      const file = new ZipDeflate(name);
+      // Zip retains member metadata until its central directory is written.
+      // Do not retain every finished compressor and its working buffers too.
+      const member = { filename: name, compression: file.compression, flag: file.flag };
+      file.ondata = (error, chunk, final) => {
+        member.size = file.size;
+        member.crc = file.crc;
+        member.ondata(error, chunk, final);
+      };
+      zip.add(member);
+      for (let offset = 0; offset < bytes.length; offset += ZIP_CHUNK_BYTES) {
+        file.push(bytes.subarray(offset, Math.min(bytes.length, offset + ZIP_CHUNK_BYTES)), false);
+      }
+      file.push(EMPTY_BYTES, true);
+    }
+    zip.end();
+    return joinChunks(chunks, size);
+  } catch (error) {
+    zip.terminate();
+    if (error instanceof IntegrationError) throw error;
+    throw archiveError('unable to write archive');
+  }
 }
 
 export { strFromU8, strToU8, MANIFEST_PATH, PARAMETERS_PROP, PARAMETERS_PROPDEF };

package/src/integration-alerts.mjs

@@ -0,0 +1,248 @@
+// Native ANS configuration inspection: rule evidence is not collection or delivery evidence.
+import { z } from 'zod';
+import { IntegrationError } from './integration-http.mjs';
+import { READ_ONLY_ANNOTATIONS, OVERWRITE_ANNOTATIONS, requireConfirmation, top, entity } from './integration-common.mjs';
+import { createCollectionPager, cursorSchema } from './integration-collections.mjs';
+import { canonicalDigest } from './integration-state.mjs';
+
+const ROOT = '/cf/configuration/v1';
+const PAGE_SIZE = 200;
+const MAX_REFERENCES = 1000;
+const MAX_OUTPUT = 60 * 1024;
+const name = z.string().min(1).max(256).regex(/^[^\x00-\x1f\x7f]+$/).refine(value => value.trim().length > 0 && value !== '.' && value !== '..', 'Invalid ANS identity');
+const names = z.array(name).min(1).max(20);
+const digest = z.string().regex(/^[a-f0-9]{64}$/).optional();
+const PREDICATES = ['CONTAINS', 'DOES_NOT_CONTAIN', 'STARTS_WITH', 'DOES_NOT_START_WITH', 'ENDS_WITH', 'DOES_NOT_END_WITH', 'EQUALS', 'NOT_EQUALS', 'ANY', 'NO_VALUE', 'LESS_THAN', 'GREATER_THAN', 'NUMBER_EQUALS'];
+const CTMS_EVENTS = new Set(['TmsImportStarted', 'TmsImportFinished', 'TmsTransportRequestAdded', 'TmsNodeImportJobDeactivated', 'TmsStorageQuotaUsage']);
+const ruleInputs = { subscription_names: names.optional(), node_names: names.optional() };
+const conditionInput = z.object({ name, propertyKey: name, predicate: z.enum(PREDICATES), propertyValue: z.string().max(4096).optional(), mandatory: z.boolean().optional() }).strict();
+const validName = value => name.safeParse(value).success;
+const safeScopeValue = value => typeof value === 'string' && /^[A-Za-z0-9_. -]{1,128}$/.test(value) && !/^[A-Za-z0-9_-]{40,}$/.test(value);
+const strings = value => Array.isArray(value) && value.every(validName) && new Set(value).size === value.length;
+const text = value => typeof value === 'string' ? value.slice(0, 256) : null;
+const issue = (code, severity = 'needs_review', reference) => ({ code, severity, ...(reference ? { reference: text(reference) } : {}) });
+const outcome = findings => findings.some(row => row.severity === 'blocked') ? 'blocked' : findings.length ? 'needs_review' : 'rules_validated';
+const sourceFailure = error => ({ result: error?.status === 401 ? 'unauthenticated' : error?.status === 403 ? 'forbidden' : error?.status === 404 || error?.status === 501 ? 'unavailable' : 'error', status: Number.isInteger(error?.status) ? error.status : null, ...(error?.code === 'INTEGRATION_DEADLINE' ? { stop_reason: 'deadline' } : {}) });
+
+function projection(kind, row) {
+  const base = { name: text(row.name) };
+  if (kind === 'action') return { ...base, type: text(row.type), state: text(row.state), fallbackAction: text(row.fallbackAction), enableDeliveryStatus: typeof row.enableDeliveryStatus === 'boolean' ? row.enableDeliveryStatus : null };
+  if (kind === 'condition') return { ...base, propertyKey: text(row.propertyKey), predicate: text(row.predicate), ...(typeof row.mandatory === 'boolean' ? { mandatory: row.mandatory } : {}), property_value: row.propertyValue === undefined ? 'absent' : 'withheld', configuration_digest: canonicalDigest(row) };
+  return { ...base, state: text(row.state), snoozeTimestamp: Number.isFinite(row.snoozeTimestamp) ? row.snoozeTimestamp : null,
+    conditions: strings(row.conditions) ? row.conditions.map(text).slice(0, 50) : null, actions: strings(row.actions) ? row.actions.map(text).slice(0, 50) : null,
+    references_truncated: (row.conditions?.length ?? 0) > 50 || (row.actions?.length ?? 0) > 50, configuration_digest: canonicalDigest(row) };
+}
+
+function decodePage(raw, page) {
+  const meta = raw?.metadata;
+  const integer = value => Number.isSafeInteger(value) && value >= 0;
+  if (!Array.isArray(raw?.results) || !meta || !['page', 'pageSize', 'totalPages', 'totalResultsCount'].every(key => integer(meta[key]))
+    || meta.page !== page || meta.pageSize !== PAGE_SIZE || meta.totalPages !== Math.ceil(meta.totalResultsCount / PAGE_SIZE) && !(meta.totalResultsCount === 0 && meta.totalPages === 1)
+    || raw.results.length !== Math.min(PAGE_SIZE, Math.max(0, meta.totalResultsCount - page * PAGE_SIZE))
+    || raw.results.some(row => !row || typeof row !== 'object' || Array.isArray(row) || !validName(row.name))
+    || new Set(raw.results.map(row => row.name)).size !== raw.results.length) throw new IntegrationError('ANS collection response has invalid paging metadata or identities');
+  return { rows: raw.results, total: meta.totalResultsCount };
+}
+
+function createReader(client) {
+  return createCollectionPager(client, { root: ROOT, request: async (method, path, options) => {
+    const skip = Number(options.query?.$skip ?? 0);
+    const page = Math.floor(skip / PAGE_SIZE);
+    const raw = await client.request('GET', `${ROOT}${path}`, { query: { page, pageSize: PAGE_SIZE }, unwrap: false, deadline: options.deadline });
+    const decoded = decodePage(raw, page);
+    return { d: { results: decoded.rows.slice(skip % PAGE_SIZE), __count: String(decoded.total) } };
+  } });
+}
+
+async function named(client, kind, value, deadline) {
+  const result = await client.request('GET', `${ROOT}/${kind}/${encodeURIComponent(value)}`, { expect: [200, 404], withStatus: true, unwrap: false, deadline });
+  if (result.status === 404) return null;
+  const row = result.data;
+  if (!row || typeof row !== 'object' || Array.isArray(row) || row.name !== value) throw new IntegrationError('ANS named response identity does not match the requested resource');
+  return entity(row);
+}
+
+function resolver(client, deadline) {
+  const cache = new Map();
+  return (kind, value) => {
+    if (!validName(value)) return Promise.reject(new IntegrationError('ANS reference identity is invalid'));
+    const key = `${kind}:${value}`;
+    if (!cache.has(key)) {
+      if (cache.size >= MAX_REFERENCES) return Promise.reject(new IntegrationError('ANS reference inspection exceeded its bounded source limit'));
+      cache.set(key, named(client, kind, value, deadline));
+    }
+    return cache.get(key);
+  };
+}
+
+// A mandatory exact condition can constrain an otherwise broad OR group. Explicit optional
+// mixtures have no locally established truth table and must never be called a verified match.
+function exactScope(conditions, key) {
+  const group = conditions.filter(row => row.propertyKey === key);
+  const mandatory = group.filter(row => row.mandatory === true);
+  const candidates = conditions.some(row => row.mandatory === true) ? mandatory : group;
+  if (!candidates.length || candidates.some(row => row.predicate !== 'EQUALS' || !safeScopeValue(row.propertyValue))) return null;
+  const values = [...new Set(candidates.map(row => row.propertyValue))];
+  if (mandatory.length && values.length !== 1) return null;
+  return values;
+}
+
+async function inspectSubscription(subscription, resolve, { node_names, now = Date.now() } = {}) {
+  const findings = [];
+  let complete = true;
+  const conditions = [];
+  const actions = [];
+  if (subscription.state === 'DISABLED') findings.push(issue('subscription_disabled', 'blocked'));
+  else if (subscription.state !== 'ENABLED') findings.push(issue('subscription_state_unknown'));
+  const snooze = subscription.snoozeTimestamp;
+  // Normalize Unix seconds; tolerate epoch-millisecond representations without exposing dates.
+  const snoozeMillis = typeof snooze === 'number' && snooze < 100_000_000_000 ? snooze * 1000 : snooze;
+  const snoozed = typeof snoozeMillis === 'number' && Number.isFinite(snoozeMillis) && snoozeMillis > now;
+  if (snoozed) findings.push(issue('subscription_snoozed', 'blocked'));
+  if (snooze !== undefined && (!Number.isSafeInteger(snooze) || snooze < 0)) findings.push(issue('subscription_snooze_unknown'));
+  const resolveRefs = async (kind, refs, target) => {
+    if (!strings(refs) || refs.length === 0 || refs.length > 50) { findings.push(issue(`${kind}_references_invalid`, 'blocked')); complete = false; return; }
+    for (const ref of refs) {
+      try {
+        const row = await resolve(kind, ref);
+        if (row) target.push(row);
+        else findings.push(issue(`${kind}_missing`, 'blocked', ref));
+      } catch (error) { complete = false; findings.push({ ...issue(`${kind}_unreadable`, 'needs_review', ref), source_result: sourceFailure(error) }); }
+    }
+  };
+  await resolveRefs('condition', subscription.conditions, conditions);
+  await resolveRefs('action', subscription.actions, actions);
+  const visited = new Set();
+  async function fallback(row, stack = new Set()) {
+    if (stack.has(row.name)) { findings.push(issue('action_fallback_cycle', 'needs_review', row.name)); return; }
+    if (visited.has(row.name)) return;
+    visited.add(row.name);
+    if (row.state === 'DISABLED') findings.push(issue('action_disabled', 'blocked', row.name));
+    else if (row.state !== 'ENABLED') findings.push(issue('action_state_unknown', 'needs_review', row.name));
+    if (row.fallbackAction !== undefined && row.fallbackAction !== null && row.fallbackAction !== '') {
+      try {
+        const next = await resolve('action', row.fallbackAction);
+        if (!next) findings.push(issue('action_missing', 'blocked', row.fallbackAction));
+        else { if (!actions.some(action => action.name === next.name)) actions.push(next); await fallback(next, new Set([...stack, row.name])); }
+      } catch (error) { complete = false; findings.push({ ...issue('action_unreadable', 'needs_review', row.fallbackAction), source_result: sourceFailure(error) }); }
+    }
+  }
+  for (const action of [...actions]) await fallback(action);
+  for (const row of conditions) {
+    if (!validName(row.propertyKey) || !PREDICATES.includes(row.predicate) || row.mandatory !== undefined && typeof row.mandatory !== 'boolean'
+      || !['ANY', 'NO_VALUE'].includes(row.predicate) && typeof row.propertyValue !== 'string'
+      || ['LESS_THAN', 'GREATER_THAN', 'NUMBER_EQUALS'].includes(row.predicate) && (typeof row.propertyValue !== 'string' || row.propertyValue.trim() === '' || !Number.isFinite(Number(row.propertyValue)))) findings.push(issue('condition_unsupported', 'needs_review', row.name));
+  }
+  if (conditions.some(row => row.mandatory === false)) findings.push(issue('explicit_optional_semantics_unverified'));
+  const eventTypes = exactScope(conditions, 'eventType');
+  const nodeNames = exactScope(conditions, 'tags.nodeName');
+  const nodeIds = exactScope(conditions, 'tags.nodeId');
+  const knownEvents = eventTypes?.every(value => CTMS_EVENTS.has(value));
+  if (!eventTypes) findings.push(issue('event_scope_unsafe'));
+  else if (!knownEvents) findings.push(issue('event_scope_unverified'));
+  if (knownEvents && !nodeNames && !nodeIds) findings.push(issue('ctms_node_scope_unsafe'));
+  if (node_names && (!nodeNames || nodeNames.some(value => !node_names.includes(value)))) findings.push(issue('requested_node_scope_unverified'));
+  if (conditions.some(row => !['eventType', 'tags.nodeName', 'tags.nodeId'].includes(row.propertyKey))) findings.push(issue('additional_condition_scope_unverified'));
+  const scoped = !findings.some(row => /scope|semantics|unsupported/.test(row.code));
+  return { ...projection('subscription', subscription), snoozed, complete, outcome: outcome(findings), findings,
+    conditions: conditions.map(row => projection('condition', row)), actions: actions.map(row => projection('action', row)),
+    scope: { event_types: knownEvents ? eventTypes : [], node_names: nodeNames ?? [], node_ids: nodeIds ?? [], verified: scoped } };
+}
+
+export async function validateNativeRules(client, args = {}, { deadline = Date.now() + 30000 } = {}) {
+  args = z.object(ruleInputs).strict().parse(args);
+  const items = [];
+  const findings = [];
+  let complete = true;
+  const resolve = resolver(client, deadline);
+  const subscriptions = [];
+  try {
+    if (args.subscription_names) {
+      for (const value of new Set(args.subscription_names)) {
+        try {
+          const row = await resolve('subscription', value);
+          if (row) subscriptions.push(row);
+          else findings.push({ ...issue('subscription_missing', 'blocked'), subscription: value });
+        } catch (error) {
+          complete = false;
+          findings.push({ ...issue('subscription_unreadable'), subscription: value, source_result: sourceFailure(error) });
+        }
+      }
+    } else {
+      let expectedTotal;
+      const seen = new Set();
+      for (let page = 0; ; page += 1) {
+        if (page >= 10) { complete = false; findings.push(issue('subscription_source_limit')); break; }
+        const decoded = decodePage(await client.request('GET', `${ROOT}/subscription`, { query: { page, pageSize: PAGE_SIZE }, unwrap: false, deadline }), page);
+        if (expectedTotal !== undefined && decoded.total !== expectedTotal || decoded.rows.some(row => seen.has(row.name))) { complete = false; findings.push(issue('subscription_source_changed')); break; }
+        expectedTotal = decoded.total;
+        decoded.rows.forEach(row => seen.add(row.name));
+        subscriptions.push(...decoded.rows);
+        if (subscriptions.length >= decoded.total) break;
+      }
+    }
+  } catch (error) { complete = false; findings.push({ ...issue('subscriptions_unreadable'), source_result: sourceFailure(error) }); }
+  if (!subscriptions.length && !findings.length) findings.push(issue('no_subscriptions', 'blocked'));
+  for (const subscription of subscriptions) {
+    const result = await inspectSubscription(subscription, resolve, args);
+    if (Buffer.byteLength(JSON.stringify({ items: [...items, result], findings }, null, 2), 'utf8') > MAX_OUTPUT) { complete = false; findings.push(issue('rule_output_limit')); break; }
+    items.push(result);
+    complete &&= result.complete;
+  }
+  const allFindings = [...findings, ...items.flatMap(item => item.findings)];
+  return { complete, delivery: 'needs_admin_confirmation', collection: 'needs_admin_confirmation', outcome: outcome(allFindings), findings, items };
+}
+
+function validateCondition(row) {
+  if (!['ANY', 'NO_VALUE'].includes(row.predicate) && row.propertyValue === undefined) throw new IntegrationError('ANS predicate requires propertyValue');
+  if (['LESS_THAN', 'GREATER_THAN', 'NUMBER_EQUALS'].includes(row.predicate) && (row.propertyValue.trim() === '' || !Number.isFinite(Number(row.propertyValue)))) throw new IntegrationError('ANS numeric predicate requires a finite numeric propertyValue');
+}
+
+async function setResource(client, kind, desired, expectedDigest, deadline) {
+  const current = await named(client, kind, desired.name, deadline);
+  if (current && (!expectedDigest || canonicalDigest(current) !== expectedDigest)) throw new IntegrationError('ANS update requires the fresh matching expected_digest');
+  if (!current && expectedDigest !== undefined) throw new IntegrationError('ANS create requires expected_digest to be absent');
+  const merged = { ...(current ?? {}), ...desired };
+  if (kind === 'condition') validateCondition(merged);
+  if (kind === 'subscription') {
+    const report = await inspectSubscription(merged, resolver(client, deadline));
+    // Disabled/snoozed is an intentional state input, not permission to bypass unsafe scope or unresolved references.
+    const blocking = report.findings.filter(row => !['subscription_disabled', 'subscription_snoozed', 'event_scope_unverified'].includes(row.code));
+    if (!report.complete || blocking.length) throw new IntegrationError('ANS subscription references or event/node scope are incomplete, unsafe or unverified; inspect native rules before writing');
+  }
+  const accepted = await client.request(current ? 'PUT' : 'POST', `${ROOT}/${kind}${current ? `/${encodeURIComponent(desired.name)}` : ''}`, {
+    json: merged, expect: [200, 201, 202, 204], withStatus: true, responseType: 'none', deadline
+  });
+  const status = accepted.status;
+  const result = { name: desired.name, operation: current ? 'update' : 'create', accepted: true, status, verified: false, delivery: 'needs_admin_confirmation' };
+  try {
+    const observed = await named(client, kind, desired.name, deadline);
+    result.verified = observed !== null && Object.entries(merged).every(([key, value]) => canonicalDigest({ value: observed[key] }) === canonicalDigest({ value }));
+    result.outcome = result.verified ? 'succeeded' : 'unverified';
+    if (observed) result.configuration = projection(kind, observed);
+  } catch (error) { result.outcome = 'unverified'; result.source_result = sourceFailure(error); }
+  return result;
+}
+
+export function registerAnsTools(register, client) {
+  const pager = createReader(client);
+  for (const [tool, kind] of [['ans_list_subscriptions', 'subscription'], ['ans_list_conditions', 'condition'], ['ans_list_action_metadata', 'action']]) {
+    register(tool, `List ANS ${kind} metadata`, 'Read bounded native alert configuration metadata using zero-based ANS paging. Condition values and action properties/recipients are withheld. Cursors are signed and runtime-bound; rule access does not prove notification delivery.',
+      { top: top(200, 100), cursor: cursorSchema }, READ_ONLY_ANNOTATIONS,
+      args => pager.page({ path: `/${kind}`, top: args.top, cursor: args.cursor, fallback: false, consistency: 'best_effort', identity: 'name', project: row => projection(kind, row), deadline: Date.now() + 30000 }));
+  }
+  register('ans_validate_native_rules', 'Validate native ANS rules', 'Resolve subscriptions, conditions and action/fallback references completely. Exact cTMS event and node scope is checked conservatively; unsupported combinations require review. Collection and notification delivery always need administrator confirmation.', ruleInputs, READ_ONLY_ANNOTATIONS,
+    args => validateNativeRules(client, args));
+  register('ans_set_condition', 'Set ANS condition', 'Create or update one condition. Exact confirmation is checked before requests. Updates require fresh canonical configuration_digest as expected_digest; creates must omit it. Metadata is preserved and values are withheld from read-back.',
+    { condition: conditionInput, expected_digest: digest, confirmation: z.string() }, OVERWRITE_ANNOTATIONS, args => {
+      requireConfirmation(args.confirmation, `SET ALERT CONDITION ${args.condition.name}`);
+      validateCondition(args.condition);
+      return setResource(client, 'condition', args.condition, args.expected_digest, Date.now() + 30000);
+    });
+  register('ans_set_subscription', 'Set ANS subscription', 'Create or update one deliberately scoped subscription, after resolving every condition/action/fallback. Exact confirmation precedes requests. Updates require expected_digest; creates omit it. No action properties or implicit all-events subscriptions are written.',
+    { name, state: z.enum(['ENABLED', 'DISABLED']), conditions: z.array(name).min(1).max(50), actions: z.array(name).min(1).max(50), expected_digest: digest, confirmation: z.string() }, OVERWRITE_ANNOTATIONS, args => {
+      requireConfirmation(args.confirmation, `SET ALERT SUBSCRIPTION ${args.name}`);
+      const { expected_digest, confirmation, ...desired } = args;
+      return setResource(client, 'subscription', desired, expected_digest, Date.now() + 30000);
+    });
+}