@aryacode/dsh-engineering 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [0.4.7] - 2026-10-25
+
+### Fixed
+
+- **`allowWrites` could not be reached from the L5X row.** The composite entry mounted the live entry
+  with no config, so the write switch had no path from the Plugins page. `entries/l5x.js` now declares
+  `allowWrites` and `allowedAddresses` and forwards both into the live entry; the write tools still
+  refuse without per-call approval.
+
+### Documentation
+
+- README: the safety section states the two keys a live write takes, the tool groups list all seven
+  EtherNet/IP tools, and the L5X count is 40 (84 with Optix).
+- `docs/examples.md`: a live section covering batch reads, discovery, the controller clock, the trend,
+  and a supervised write with the exact fields the reader must see and the refusals they may hit.
+- `docs/architecture.md`: a new EtherNet/IP section — the two workers, the transaction engine's deadline
+  and decoding, and the four gates that stand between a write request and a controller.
+- `docs/port/l5x.md`: the live surface is recorded as seven tools with the driver call each one uses, and
+  the unused capability (CIP subscriptions, UDT `Structure` reads) is named.
+- `packages/l5x/README.md`: read and write tool tables, and the full live configuration row.
+
+## [0.4.6] - 2026-10-25
+
+### Added
+
+The EtherNet/IP surface now uses the driver rather than one corner of it. Five new tools, all under the
+L5X product row's `live` switch:
+
+- `read_live_tags` — up to 64 declared scalars in **one** request (CIP tag group) instead of one
+  connection-and-read per tag.
+- `read_controller_clock` — controller identity plus the wall clock beside the workstation clock and the
+  offset between them; reports "unsupported" on non-L8x models instead of guessing.
+- `discover_controllers` — bounded UDP broadcast discovery: address, product, revision, serial, status.
+  Needs no address and no export.
+- `write_live_tag` — one declared scalar, **approval-gated**, then read back over CIP so the result is
+  the controller's own value.
+- `write_controller_clock` — set the wall clock (L8x), approval-gated, read back.
+
+### Safety
+
+- Writes need **two** independent switches: the row's new `allowWrites` config (off by default) **and** a
+  human approving that exact operation. With `allowWrites` on and a `never` approval policy the tool
+  refuses with `APPROVAL_UNAVAILABLE`; a declined prompt is `APPROVAL_DENIED`. Nothing reaches a
+  controller before both pass.
+- Every write validates against the open export first: declared, not an alias, no array dimensions,
+  `ExternalAccess` not `None`, value inside the declared type and range (BOOL boolean; INT/DINT integer
+  within range; REAL finite).
+- A write whose readback differs from the requested value fails with `WRITE_NOT_VERIFIED` rather than
+  reporting success.
+- `test/live.spec.ts` covers the gating: switch off, policy `never`, declined prompt, wrong value type,
+  and a UDT tag refused as non-scalar — 70 tests in the package.
+
 ## [0.4.5] - 2026-10-25
 
 ### Changed

package/README.md

@@ -4,7 +4,7 @@
 MotionWorks IEC and FactoryTalk Optix sit behind a single install, one row per surface. A row is the
 switch: disable it and that plugin unloads, so its tool schemas leave the request.
 
-`@aryacode/dsh-engineering` · 79 tools · 5 rows · 4 products · MIT
+`@aryacode/dsh-engineering` · 84 tools · 5 rows · 4 products · MIT
 
 ---
 
@@ -21,7 +21,8 @@ the row, off by default, so a read-only profile pays for the read tools and noth
 |---|---|---|---|
 | `l5x` | `editing` | off | the nine `draft_*` schemas |
 | `l5x` | `studio` | off | the Logix Designer SDK and supervised controller schemas |
-| `l5x` | `live` | off | the EtherNet/IP polling and trend schemas |
+| `l5x` | `live` | off | the EtherNet/IP read, batch, discovery, clock and trend schemas |
+| `l5x` | `allowWrites` | off | the two approval-gated writes (tag, wall clock) |
 | `ftview` | `edit`, `studio` | on | staged ME edits and the Studio handoff |
 | `mwi` | `edit` | off | the seven MotionWorks edit schemas |
 
@@ -33,7 +34,7 @@ bundle.
 
 | Product | Tools | Default | Needs |
 |---|---|---|---|
-| **Studio 5000 L5X** | 35 | read on; edit, Studio, live **off** | Node for offline reads; Studio 5000 + Logix Designer SDK for SDK work; a controller for live |
+| **Studio 5000 L5X** | 40 | read on; edit, Studio, live **off** | Node for offline reads; Studio 5000 + Logix Designer SDK for SDK work; a controller for live |
 | **FactoryTalk View ME** | 14 | all on | Node for an export folder; FactoryTalk View Studio ME for discovery and the handoff |
 | **MotionWorks IEC** | 24 | session, read, verify on; edit **off** | MotionWorks IEC 3 Pro installed; verified against 1.19 |
 | **FactoryTalk Optix** | 6 | on | Optix Studio installed |
@@ -41,7 +42,7 @@ bundle.
 Tool groups, by product:
 
 - **L5X** — 11 read (`open_project` … `compare_projects`), 9 staged drafts (`draft_*`), 6 Logix
-  Designer SDK, 7 supervised controller, 2 live EtherNet/IP
+  Designer SDK, 7 supervised controller, 7 live EtherNet/IP (2 reads, 2 identity/discovery, 1 batch read, 2 approval-gated writes)
 - **FactoryTalk View** — 6 read, 5 staged edits, 3 Studio handoff
 - **MotionWorks IEC** — 7 session, 7 saved-project reads, 3 verify, 7 staged edits
 - **Optix** — 6 tools, unlinked to a skill until one exists
@@ -55,7 +56,7 @@ down:
 
 | Row | Mounts | Config options (default) |
 |---|---|---|
-| `l5x` | offline reads, checks, comparison and the `rockwell-l5x` guidance; optionally drafts, SDK, live | `editing` (off), `studio` (off), `live` (off) |
+| `l5x` | offline reads, checks, comparison and the `rockwell-l5x` guidance; optionally drafts, SDK, live (reads, batch, discovery, clock) and supervised writes | `editing` (off), `studio` (off), `live` (off), `allowWrites` (off) |
 | `ftview` | FactoryTalk View ME read, guidance and edits; optionally the Studio handoff | `edit` (on), `studio` (on) |
 | `mwi` | MotionWorks IEC session, reads, verify and guidance; optionally the edits | `edit` (off) |
 | `viewers` | ladder + ME display previews | — |
@@ -86,19 +87,20 @@ Where each surface actually stands, based on what has been exercised.
 - Logix Designer SDK: a real ACD exported to a 3.0 MB L5X against SDK v37
 - Supervised controller access — upload, mode change and download behind per-call approval, with
   downloads accepting only a verification id produced by a passed build
-- Live EtherNet/IP reads and a bounded PLC trend
+- Live EtherNet/IP: polling, one-request batch reads of up to 64 tags, controller identity and clock, LAN discovery, and a bounded trend
+- Supervised live writes: `write_live_tag` and `write_controller_clock` need the row's `allowWrites` switch **and** per-call human approval, and report the value the controller reads back
 - FactoryTalk View ME: export reads, structural checks, comparison, staged display and HMI tag edits
 - MotionWorks IEC: verified live against 3 Pro 1.19 — stage, start, worksheet, close, saved-project
   reads, compile diagnostics, code replacement, declaration add, POU create/delete, block insertion
   and a POU package export/delete/import round trip
 - Ladder viewer and FactoryTalk View display preview
 
-**Deliberately off by default** — enabled per profile: `l5x-editing`, `l5x-studio`, `l5x-live`,
+**Deliberately off by default** — enabled per profile: `l5x-editing`, `l5x-studio`, `l5x-live`, `allowWrites`,
 `mwi-edit`. A read-only profile should not pay for nine draft schemas or a controller surface.
 
 **Known limits** — stated in the bundle, not hidden:
 
-- Live reads and SDK builds cannot establish that online logic matches the export; every result says
+- Live reads, SDK builds and live writes cannot establish that online logic matches the export; every result says
   so in `coverage`
 - FBD/SFC semantics are not exercised
 - FactoryTalk View Studio work is a **manual handoff**: the bundle plans the import and preflights
@@ -113,6 +115,7 @@ Where each surface actually stands, based on what has been exercised.
 |---|---|
 | **0.4.4** | One row per product: five rows, optional surfaces moved into each row's config |
 | **0.4.0** | Both previews fold into the bundle's own client face — one package, one browser bundle, 16 rows |
+| **0.4.6** | Full EtherNet/IP surface: batch reads, discovery, controller clock, and approval-gated tag and clock writes; 84 tools |
 | **0.3.0** | FactoryTalk Optix becomes a bundle component; 79 tools total |
 | **0.2.0** | MotionWorks IEC ports into the bundle — 24 tools over the COM bridge and saved-model engine, verified live; edit off by default |
 | **0.1.2** | Harness filesystem contract fixed across L5X and FactoryTalk View; every L5X tool linked to its capability by name; generated tool reference, examples and architecture docs |
@@ -173,6 +176,9 @@ even when the implementation behind a row is replaced.
 - **Controller changes need a human.** Upload, mode change and download require per-call approval and
   a session policy that permits asking. The tools refuse before contacting a controller when approval
   is unavailable, and a download accepts only a verification id produced by a passed build.
+- **Live writes take two keys.** `write_live_tag` and `write_controller_clock` need the row's
+  `allowWrites` switch *and* approval for that exact write; the tag is validated against the export
+  first and the result is the value the controller reads back (`WRITE_NOT_VERIFIED` if it differs).
 - **No hidden vendor execution.** The FactoryTalk View Studio handoff returns a manual import plan; it
   does not run a vendor utility.
 - **Coverage is stated.** Every result names what it cannot establish, including whether online logic

package/entries/l5x.js

@@ -2,10 +2,14 @@
  * The Studio 5000 L5X product row: one switch for the whole L5X surface.
  *
  * The parts are the vendored entries; this module mounts them, so the Plugins
- * page shows one row per product instead of one per surface. The three
- * expensive surfaces stay off by default and are switched from this row's
- * config form, which is the same decision the old separate rows encoded —
- * just reachable from the product row instead of from the list.
+ * page shows one row per product instead of one per surface. The expensive
+ * surfaces stay off by default and are switched from this row's config form,
+ * which is the same decision the old separate rows encoded — just reachable
+ * from the product row instead of from the list.
+ *
+ * `allowWrites` is forwarded into the live entry, not consumed here: the write
+ * tools refuse from inside that entry, so the switch and the per-call approval
+ * both live where the controller traffic happens.
  */
 import z from '@deepseek-ai/schemastery'
 import * as read from '../vendor/l5x/lib/index.js'
@@ -26,19 +30,31 @@ export const Config = z.object({
     'Logix Designer SDK and supervised controller tools. Needs Studio 5000 with the SDK service installed.',
   ),
   live: z.boolean().default(false).description(
-    'EtherNet/IP polling and trend tools. Needs a reachable controller address.',
+    'EtherNet/IP surface: polling, batch reads, discovery, controller clock and trends. Needs a reachable controller address.',
+  ),
+  allowWrites: z.boolean().default(false).description(
+    'Permit the two live write tools (tag, wall clock). Each write still needs human approval for that exact operation, and only applies while live is on.',
+  ),
+  allowedAddresses: z.array(z.string()).default([]).description(
+    'Optional IPv4 allowlist for live reads, writes and discovery. Empty permits any explicit address.',
   ),
 })
 
 /**
  * Mount the L5X surface.
  * @param ctx - plugin context.
- * @param config - the three optional surfaces, all off unless enabled.
+ * @param config - the optional surfaces, all off unless enabled.
  */
 export function apply(ctx, config = {}) {
   ctx.plugin(read)
   ctx.plugin(skill)
   if (config.editing === true) ctx.plugin(editing)
   if (config.studio === true) ctx.plugin(studio)
-  if (config.live === true) ctx.plugin(live)
+  if (config.live === true) {
+    const addresses = Array.isArray(config.allowedAddresses) ? config.allowedAddresses : []
+    ctx.plugin(live, {
+      allowWrites: config.allowWrites === true,
+      ...(addresses.length === 0 ? {} : { allowedAddresses: addresses }),
+    })
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryacode/dsh-engineering",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "AryaCode engineering bundle: one install surface for the Studio 5000 L5X, FactoryTalk View ME, MotionWorks IEC and FactoryTalk Optix surfaces, one row per product, with the ladder and display previews.",
   "keywords": [
     "dsh",

package/vendor/l5x/README.md

@@ -7,7 +7,7 @@ Studio 5000 L5X tools for the `dsh-engineering` bundle. Four loader entries shar
 | `dsh-engineering-l5x` | 11 offline read and reference tools | Node |
 | `dsh-engineering-l5x/editing` | 9 `draft_*` tools | the read entry |
 | `dsh-engineering-l5x/studio` | 6 Logix Designer SDK tools and 7 supervised controller tools | Studio 5000, Logix Designer SDK, FactoryTalk Linx |
-| `dsh-engineering-l5x/live` | `poll_live_tags`, `start_plc_trend` | a reachable controller |
+| `dsh-engineering-l5x/live` | 7 EtherNet/IP tools: `poll_live_tags`, `read_live_tags`, `read_controller_clock`, `discover_controllers`, `start_plc_trend`, and the approval-gated `write_live_tag`, `write_controller_clock` | a reachable controller for reads; the row's `allowWrites` plus human approval for writes |
 
 The `rockwell-l5x` guidance ships as the separate `dsh-engineering-l5x/skill` entry, and the PLC
 trend card ships as the client face (`dsh.client`).
@@ -40,9 +40,31 @@ operation is an upload, mode change or download; those require per-call human ap
 
 ## Live
 
-`poll_live_tags` and `start_plc_trend` read declared scalar tags over EtherNet/IP without Studio,
-Linx, an ACD or the SDK. They are read-only and report that live logic matching the export is
-unverified.
+Reads need no approval and no Studio, Linx, ACD or SDK:
+
+| Tool | What it does |
+|---|---|
+| `poll_live_tags` | Timed sweeps of 1–16 declared scalar tags, with quality and controller identity |
+| `read_live_tags` | Up to 64 declared scalars in **one** request (CIP tag group) |
+| `read_controller_clock` | Identity plus the wall clock beside the workstation clock and their offset (L8x) |
+| `discover_controllers` | Bounded UDP broadcast discovery of EtherNet/IP devices on the LAN |
+| `start_plc_trend` | Session-owned trend job the chart follows without a model call per sample |
+
+Two writes exist and are **supervised**, not merely available:
+
+| Tool | What it changes |
+|---|---|
+| `write_live_tag` | One declared scalar, then read back over CIP |
+| `write_controller_clock` | The controller wall clock (L8x), then read back |
+
+A write needs the row's `allowWrites` switch **and** a human approving that exact operation: with
+`allowWrites` on and a `never` policy the tool refuses with `APPROVAL_UNAVAILABLE` before opening a
+socket, and a declined prompt is `APPROVAL_DENIED`. Each write is validated against the open export
+(declared, non-alias, no array dimensions, `ExternalAccess` not `None`, value inside the declared
+type and range) and a readback that differs fails with `WRITE_NOT_VERIFIED`.
+
+Every read reports that live logic matching the export is unverified, and sequential reads can miss
+transitions between sweeps.
 
 ## Configuration
 
@@ -51,7 +73,7 @@ unverified.
 | read | `maxFileBytes` | 64 MiB |
 | editing | `maxFileBytes`, `maxDraftOperations` | 64 MiB, 200 |
 | studio | `maxFileBytes` | 64 MiB |
-| live | `enabled`, `minIntervalMs`, `defaultIntervalMs`, `maxTags`, `maxSamples` | true, 50 ms, 200 ms, 16, 1200 |
+| live | `enabled`, `minIntervalMs`, `defaultIntervalMs`, `maxTags`, `maxSamples`, `allowWrites`, `maxBatchTags`, `allowedAddresses` | true, 50 ms, 200 ms, 16, 1200, false, 64, empty |
 
 ## Develop
 

package/vendor/l5x/cip-worker.mjs

@@ -0,0 +1,181 @@
+/** Isolated one-shot EtherNet/IP transactions. The parent owns deadlines, approval and validation. */
+import { isMainThread, parentPort, workerData } from 'node:worker_threads'
+import { setTimeout as delay } from 'node:timers/promises'
+import ethernetIp from 'st-ethernet-ip'
+import { isIPv4 } from 'node:net'
+
+/** Shape one tag address for output. */
+function addressOf(entry) {
+  return entry.program === undefined ? entry.name : `Program:${entry.program}.${entry.name}`
+}
+
+/** One observed value, quality included. */
+function readValue(entry, tag) {
+  const typeMatches = tag.type === entry.data_type
+  const scalar = typeof tag.value === 'boolean' || (typeof tag.value === 'number' && Number.isFinite(tag.value))
+  return {
+    tag: addressOf(entry),
+    data_type: entry.data_type,
+    actual_data_type: tag.type,
+    value: typeMatches && scalar ? tag.value : null,
+    quality: typeMatches && scalar ? 'good' : 'bad',
+    ...typeMatches && scalar ? {} : { error: 'Live type or value differs from the export declaration' },
+  }
+}
+
+/**
+ * Open a controller, run one operation, and always close the connection.
+ *
+ * @param {object} spec Validated worker request.
+ * @returns {Promise<object>} The operation's result value.
+ */
+async function connectAndRun(spec, run) {
+  if (!spec || typeof spec.ip !== 'string' || !isIPv4(spec.ip) || !Number.isInteger(spec.slot) || spec.slot < 0 || spec.slot > 31
+    || !Number.isInteger(spec.timeout) || spec.timeout < 1)
+    throw new Error('Invalid CIP worker request')
+  const plc = new ethernetIp.Controller(false)
+  plc.timeout_sp = spec.timeout
+  // Driver transport failures are reported per request; keep the socket event handled.
+  plc.on('error', error => { void error })
+  try {
+    await plc.connect(spec.ip, spec.slot, false)
+    await plc.readControllerProps()
+    const controller = {
+      product_name: plc.properties.name,
+      serial_number: plc.properties.serial_number,
+      revision: plc.properties.version,
+      status: plc.properties.status,
+    }
+    return await run(plc, controller)
+  } finally {
+    // Unconnected explicit messaging needs no Forward Close request.
+    const closed = new Promise(resolve => plc.once('close', resolve))
+    if (!plc.closed) { if (!plc.destroyed) plc.destroy(); await closed }
+  }
+}
+
+/** Batch read: one explicit request carries every tag in the group. */
+async function read(spec) {
+  return await connectAndRun(spec, async (plc, controller) => {
+    const group = new ethernetIp.TagGroup()
+    const tags = spec.tags.map(entry => {
+      if (!entry || typeof entry.name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(entry.name)
+        || !['BOOL', 'INT', 'DINT', 'REAL'].includes(entry.data_type)
+        || (entry.program !== undefined && (typeof entry.program !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(entry.program))))
+        throw new Error('Invalid CIP worker tag')
+      const tag = new ethernetIp.Tag(entry.name, entry.program)
+      group.add(tag)
+      return { entry, tag }
+    })
+    await plc.readTagGroup(group)
+    return {
+      controller,
+      request_count: 1,
+      observed_at: new Date().toISOString(),
+      values: tags.map(({ entry, tag }) => ({ ...readValue(entry, tag), observed_at: new Date().toISOString() })),
+    }
+  })
+}
+
+/** Identity and wall clock; the clock exists only on L8x controllers. */
+async function clock(spec) {
+  return await connectAndRun(spec, async (plc, controller) => {
+    try {
+      await plc.readWallClock()
+      return {
+        controller,
+        supported: true,
+        controller_time: plc.properties.time instanceof Date ? plc.properties.time.toISOString() : String(plc.properties.time),
+        host_time: new Date().toISOString(),
+      }
+    } catch (error) {
+      return {
+        controller,
+        supported: false,
+        host_time: new Date().toISOString(),
+        reason: error instanceof Error ? error.message : 'Wall clock is unavailable on this controller',
+      }
+    }
+  })
+}
+
+/** One tag write, read back over CIP so the result is the controller's answer. */
+async function write(spec) {
+  return await connectAndRun(spec, async (plc) => {
+    const entry = spec.tag
+    const tag = new ethernetIp.Tag(entry.name, entry.program)
+    // Read first: the driver needs the controller's own type to encode the write.
+    await plc.readTag(tag)
+    const before = tag.value
+    const actualType = tag.type
+    tag.value = spec.value
+    await plc.writeTag(tag)
+    await plc.readTag(tag)
+    const readback = tag.value
+    return {
+      tag: addressOf(entry),
+      declared_data_type: entry.data_type,
+      actual_data_type: actualType,
+      previous_value: before,
+      requested_value: spec.value,
+      readback,
+      verified: Object.is(readback, spec.value) || (typeof readback === 'number' && typeof spec.value === 'number' && Math.abs(readback - spec.value) < 1e-6),
+      written_at: new Date().toISOString(),
+    }
+  })
+}
+
+/** Set the wall clock; L8x only, and read back to prove it landed. */
+async function writeClock(spec) {
+  return await connectAndRun(spec, async (plc) => {
+    const target = new Date(spec.iso)
+    if (Number.isNaN(target.getTime())) throw new Error('Invalid wall clock timestamp')
+    await plc.writeWallClock(target)
+    await plc.readWallClock()
+    const readback = plc.properties.time instanceof Date ? plc.properties.time.toISOString() : String(plc.properties.time)
+    return { requested_time: target.toISOString(), readback, verified: Math.abs(Date.parse(readback) - target.getTime()) < 2000 }
+  })
+}
+
+/** UDP broadcast discovery: where are the controllers on this LAN. */
+async function discover(spec) {
+  const browser = new ethernetIp.Browser()
+  const devices = new Map()
+  browser.on('Device List Updated', list => {
+    for (const device of list) {
+      const address = device?.socketAddress?.sin_addr
+      if (typeof address === 'string') devices.set(address, device)
+    }
+  })
+  browser.on('error', error => { void error })
+  try {
+    browser.start()
+    await delay(spec.duration)
+  } finally {
+    browser.stop()
+  }
+  return {
+    seconds: spec.duration / 1000,
+    devices: [...devices.entries()].map(([ip, device]) => ({
+      ip_address: ip,
+      product_name: String(device.productName ?? ''),
+      revision: String(device.revision ?? ''),
+      serial_number: String(device.serialNumber ?? ''),
+      vendor_id: Number(device.vendorID ?? 0),
+      device_type: Number(device.deviceType ?? 0),
+      status: Number(device.status ?? 0),
+    })),
+  }
+}
+
+const OPERATIONS = { read, clock, write, 'write-clock': writeClock, discover }
+
+if (!isMainThread) {
+  try {
+    const operation = OPERATIONS[workerData?.op]
+    if (operation === undefined) throw new Error('Unknown CIP worker operation')
+    parentPort.postMessage({ ok: true, value: await operation(workerData) })
+  } catch (error) {
+    parentPort.postMessage({ ok: false, message: error instanceof Error ? error.message : 'Controller transaction failed' })
+  } finally { parentPort.close() }
+}

package/vendor/l5x/lib/core/params.d.ts

@@ -9,7 +9,7 @@
  */
 /** One JSON Schema property, with the description that is mandatory here. */
 export interface ParameterSchema {
-    readonly type: 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object';
+    readonly type: 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object' | readonly ('string' | 'integer' | 'number' | 'boolean')[];
     readonly description: string;
     readonly enum?: readonly string[];
     readonly items?: ParameterSchema;
@@ -28,6 +28,8 @@ export declare function string(description: string, extra?: Partial<ParameterSch
 export declare function integer(description: string, extra?: Partial<ParameterSchema>): ParameterSchema;
 /** A string parameter restricted to a known set. */
 export declare function choice(description: string, values: readonly string[], extra?: Partial<ParameterSchema>): ParameterSchema;
+/** A boolean-or-number parameter, for a value whose real type comes from the project. */
+export declare function scalar(description: string, extra?: Partial<ParameterSchema>): ParameterSchema;
 /** An array of one parameter type. */
 export declare function list(description: string, items: ParameterSchema, extra?: Partial<ParameterSchema>): ParameterSchema;
 /** One object element of an array parameter. */

package/vendor/l5x/lib/core/params.js

@@ -19,6 +19,10 @@ export function integer(description, extra = {}) {
 export function choice(description, values, extra = {}) {
     return { type: 'string', description, enum: values, ...extra };
 }
+/** A boolean-or-number parameter, for a value whose real type comes from the project. */
+export function scalar(description, extra = {}) {
+    return { type: ['boolean', 'number'], description, ...extra };
+}
 /** An array of one parameter type. */
 export function list(description, items, extra = {}) {
     return { type: 'array', description, items, ...extra };

package/vendor/l5x/lib/engine/cip-request.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Validation for one-shot controller transactions.
+ *
+ * Nothing here opens a socket. Every argument is resolved against the open
+ * export first, so a mistyped tag, an alias, an array or a type-mismatched write
+ * is refused before the controller is contacted.
+ *
+ * @module dsh-engineering-l5x/engine/cip-request
+ */
+import { type ProjectSnapshot } from '../session.ts';
+import type { PollingConfig } from './direct-polling.ts';
+/** Scalar types this surface can read and write. */
+declare const SCALARS: readonly ["BOOL", "INT", "DINT", "REAL"];
+type Scalar = (typeof SCALARS)[number];
+/** One resolved scalar address. */
+export interface ScalarTag {
+    name: string;
+    program?: string;
+    data_type: Scalar;
+}
+/**
+ * Resolve the controller address and slot both read and write share.
+ * @param input - Tool arguments.
+ * @param config - Resolved deployment limits.
+ * @returns The validated target.
+ */
+export declare function controllerTarget(input: Readonly<Record<string, unknown>>, config: PollingConfig): {
+    ip: string;
+    slot: number;
+    timeout: number;
+};
+/**
+ * Resolve declared scalar tags for a batch read, then bound the batch.
+ * @param project - Fresh export snapshot.
+ * @param input - Tool arguments carrying `tags`.
+ * @param config - Resolved deployment limits.
+ * @param maxBatch - Largest accepted batch.
+ * @returns Worker request and operand evidence.
+ */
+export declare function batchReadRequest(project: ProjectSnapshot, input: Readonly<Record<string, unknown>>, config: PollingConfig, maxBatch: number): {
+    request: {
+        tags: ScalarTag[];
+        ip: string;
+        slot: number;
+        timeout: number;
+        op: string;
+    };
+    evidence: {
+        tag: string;
+        scope: string;
+        references: import("./analysis.ts").Evidence[];
+        reference_completeness: string;
+    }[];
+};
+/**
+ * Resolve one writable scalar and check the value against its declared type.
+ * @param project - Fresh export snapshot.
+ * @param input - Tool arguments carrying `name`, optional `program`, and `value`.
+ * @param config - Resolved deployment limits.
+ * @returns The validated worker request.
+ */
+export declare function writableTagRequest(project: ProjectSnapshot, input: Readonly<Record<string, unknown>>, config: PollingConfig): {
+    request: {
+        tag: ScalarTag;
+        value: number | boolean;
+        ip: string;
+        slot: number;
+        timeout: number;
+        op: string;
+    };
+};
+/**
+ * Bound a discovery window.
+ * @param input - Tool arguments carrying optional `duration_seconds`.
+ * @param config - Resolved deployment limits.
+ * @returns Worker request with the window in milliseconds.
+ */
+export declare function discoverRequest(input: Readonly<Record<string, unknown>>, config: PollingConfig): {
+    request: {
+        op: string;
+        duration: number;
+        timeout: number;
+    };
+};
+export {};