@aryacode/dsh-engineering 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 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

package/README.md

@@ -176,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.6",
+  "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