Release 0.5.0

Directory.Build.props

@@ -7,7 +7,7 @@
          내지 않는다 — 다음 판에 같이 나간다). 올린 번호는
          다시 쓰지 않는다 — NuGet 은 지울 수도 덮어쓸 수도 없다. publish.yml 이 태그와 이 값이 같은지, 태그 커밋이
          main 에 있는지 검사하고, 태그가 아닌 ref 에서는 올리지 않는다. -->
-    <Version>0.4.1</Version>
+    <Version>0.5.0</Version>
 
     <Authors>kintaein</Authors>
     <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>

docs/design-requirements.md

@@ -61,7 +61,7 @@ holds today and nothing would notice a regression. `partial` = some cases guarde
 | R9 | met | `FormulaParser.cs:270,277` (depth 200); `NodeBinder.cs:179-239` — **iterative** DFS, so cyclic XML cannot overflow the stack | `NodeMapBindTests.ReferenceCycle_IsDetectedAtBind`, `FormulaTests.DeepParenthesesAreRejectedWithoutStackOverflow` |
 | R10 | met | `GenApi/Runtime/IntegerNodes.cs:365-380` (`FieldOf` flips LSB/MSB for BigEndian) | `IntegerNodeTests.MaskedIntReg_BigEndian_Bit0_IsMostSignificantBit`, `MaskedIntReg_LittleEndian_Lsb0Msb7_IsLowByte`, `MaskedIntReg_BitBeyondRegister_FailsAtBind` |
 | R11 | met | `Gvsp/GevStream.PacketSize.cs:26-65,78,157`; SCPD from the option only | `PacketSizeNegotiationTests.*`, `StreamingScenarioTests.Start_AccessesChannelRegistersInTheDocumentedOrder_AndStopReversesIt` |
-| R12 | met | `Gvsp/GevStream.cs` (granted socket buffer read back and logged, dedicated receiver thread), `Receiver.cs` (one reusable scratch buffer, pooled slots and frame buffers) | `ReceiverAllocationTests` — the receiver's per-datagram work is called on the test thread (`FeedPacketForTest`), so `GC.GetAllocatedBytesForCurrentThread` can see it: 0 bytes across 700+ packets, 0 bytes for late/duplicate packets of a closed block, and completing a frame allocates only the `GevFrame` object (≤ 256 bytes, not the 64 KiB image). Mutation-checked: one unguarded interpolated `GevLog.Debug` on the packet path fails both. `GvcpChannelTests.PacketResendDoesNotAllocateOnTheHotPath` guards the GVCP side |
+| R12 | met (one runtime exception, 2026-09-26) | **Exception:** on .NET Framework (the netstandard2.0 asset) the receiver's wait allocates — `Socket.Poll` there allocates a small array per call (about 40 B, measured; 0 B on net6/net8), and the receiver polls whenever the socket is empty, about once per packet at full rate. Accepted: the previous zero-allocation wait (blocking receive with a socket receive timeout) lost datagrams on Windows (`docs/evaluation.md`, "Receive wait on Windows"). `ReceiverAllocationTests` feed packets past the socket, so they do not see the wait. Otherwise: `Gvsp/GevStream.cs` (granted socket buffer read back and logged, dedicated receiver thread), `Receiver.cs` (one reusable scratch buffer, pooled slots and frame buffers) | `ReceiverAllocationTests` — the receiver's per-datagram work is called on the test thread (`FeedPacketForTest`), so `GC.GetAllocatedBytesForCurrentThread` can see it: 0 bytes across 700+ packets, 0 bytes for late/duplicate packets of a closed block, and completing a frame allocates only the `GevFrame` object (≤ 256 bytes, not the 64 KiB image). Mutation-checked: one unguarded interpolated `GevLog.Debug` on the packet path fails both. `GvcpChannelTests.PacketResendDoesNotAllocateOnTheHotPath` guards the GVCP side |
 | R13 | met | `Gvcp/GevDiscovery.cs` — `SelectInterfaces` enumerates every up IPv4 interface, `BuildTargets` forms the limited and directed broadcasts; `GevNet.cs` (`GetIpv4Interfaces`, `DirectedBroadcast`) | `GevDiscoveryTests.Probe*`, `DiscoverCollectsRepliesFromEveryTargetAndDedupesByMac`, and `DiscoveryBroadcastTests` (11 cases: per-mask directed address, unknown mask, /0 collapsing onto the limited one, unicast appended not substituted, loopback opt-in enumeration, and both broadcasts observed leaving the socket) — mutation-checked: forcing `DirectedBroadcast` off fails 7 |
 | R14 | met | `GevDiscovery.cs:214-218,284-288`; `GevDeviceInfo.cs:52` | `GevDiscoveryTests.DiscoverSkipsTruncatedRepliesInsteadOfCreatingGhosts`, `ProbeSkipsTruncatedDiscoveryAck` |
 | R15 | met | `Gvcp/GvbsAddr.cs` (the offset table), `GevDeviceInfo.cs:55-101`, `GevDevice.cs:113-116` — the only name lookup in the library is `TLParamsLocked`, which is not a bootstrap register | `GevDeviceInfoReadTests.EveryFieldIsReadAtItsOwnAddress`, `OpenIsNotFooledByADeviceWhoseBulkReadSkipsUnimplementedWords` |

docs/evaluation.md

@@ -222,8 +222,39 @@ resumes later, would otherwise see the stream go permanently silent with no erro
 Three defects were found here that no simulator run had shown, each now fixed and guarded by a test:
 the transport-layer lock (`TLParamsLocked`) that gates the acquisition commands, the host firewall that
 silently swallowed every GVSP packet, and GenApi addresses above 32 bits that made the whole File Access
-category unreadable. A fourth was cosmetic but real: a blocking receive can return `IOPending` on Windows,
-which the receiver logged as an error and answered with a sleep.
+category unreadable. A fourth looked cosmetic at the time: a blocking receive can return `IOPending` on Windows,
+which the receiver logged as an error and answered with a sleep. It was not cosmetic — see the next section.
+
+### Receive wait on Windows: a timed-out blocking receive loses datagrams (2026-09-26)
+
+*Bench measurement with the CLI harness (`samples/GevSharp.Cli`): protocol layer only, no consumer application in the path.*
+
+Up to 0.4.1 the receiver waited for packets with a blocking receive and a socket receive timeout
+(`SO_RCVTIMEO`), 2 ms while a frame is being assembled and 200 ms when idle, and treated `IOPending` like a
+timeout. Windows documents the socket state after a timed-out blocking receive as indeterminate, and in
+practice a datagram that arrives at the moment the timeout expires can be lost. A loopback probe under load
+lost exactly as many datagrams as it saw `IOPending` returns.
+
+On hardware the condition is packets spaced wider than the wait interval, so that every packet arrives just
+after a wait ends: slow senders, a large inter-packet delay (SCPD), bandwidth shared between cameras, or a
+device that sends the leader long before the payload. Basler acA2500-14gm, Mono8 2592x1944, SCPD 300000 ticks
+(about 2.4 ms between packets), resend off so a loss is not hidden, three concurrent test runs as CPU load,
+60 s per run:
+
+| Receiver | Run | Blocks | Incomplete | Missing packets |
+|---|---|---|---|---|
+| 0.3.0 CLI (`SO_RCVTIMEO` wait) | 1 | 46 | 9 | 10 |
+| 0.3.0 CLI (`SO_RCVTIMEO` wait) | 2 | 39 | 8 | 9 |
+| this tree (non-blocking receive + `Poll`) | 1 | 39 | 0 | 0 |
+| this tree (non-blocking receive + `Poll`) | 2 | 39 | 0 | 0 |
+
+With resend on, each such loss costs a resend request instead of a frame, which is why the full-rate runs
+above never showed it: back-to-back packets do not leave the 2 ms gaps. At full rate the new wait changes
+nothing measurable: 120 s, 1752 frames, 989,880 packets, 14.59 fps, 0 resend requests, the same as before.
+The receiver now receives non-blocking while data is queued and waits with `Poll` (which does not consume
+data) only when the socket is empty. `GevSharp.Tests` has an opt-in load test for the loopback case
+(`ReceiveWaitLossTests`, `GEVSHARP_STRESS=1`); it did not reproduce the loss in 2,800 frames on the old code,
+so the hardware table is the evidence.
 
 ### Odd-width GVSP Packed line rule — settled by measurement, and we had it wrong
 
@@ -273,6 +304,28 @@ clamped at the expected size. This matters since frame completion also requires
 frame closed as incomplete, with the one-time warning naming both sizes. Not observed on this camera; the rule
 is left as is until a device shows it, and the warning is what would surface it.
 
+**Blocks at acquisition stop (2026-09-26, reported through the CvInspect adapter — not a CLI harness run).** The
+same R29 check closes a block that a device cuts short with an early trailer. The consumer ran GevSharp 0.4.1
+through its adapter on this camera with single grabs, live bursts, 1 ms-timeout grabs that stop acquisition while
+a frame is in flight, and cancellations 0–3 ms after the call. The first run ended with 0 incomplete. The second
+run of the same procedure had **one cut block**: during the cancellation series, block 55 ended with a trailer
+after 431 payload packets — 3,856,896 of the 5,038,848 bytes the leader announced — and was closed as
+incomplete with the one-time warning. This is the first hardware observation of the case R29 guards: 0.4.0 would
+have delivered that frame as complete with the previous frame's pixels in its missing part. So this Basler
+**sometimes** cuts the block it is sending when acquisition is stopped; one clean run did not show it, and one
+such run is not evidence that a model never cuts. In the same run the next single grab timed out once (2 s).
+
+The consumer then ran a 0.4.0 control with the same adapter source and procedure (cancel 0–3 ms after the call ×20,
+then five normal grabs; eight rounds). Both versions saw the device cut blocks with an early trailer ("trailer sets
+packet count 563 -> 552" and similar), and some of the cut blocks were the frame of the **normal grab right after
+a cancellation round** — no packet was missing and no resend was asked; the device sent the trailer early.
+0.4.1 closed those frames as incomplete, so that grab timed out (packets arrived in the window, 0 completed,
+1 incomplete). 0.4.0 returned the cut frame as that grab's answer, marked complete, with its last 12–14 packets'
+worth of bytes still holding the previous frame. So the timeout is not a receiver regression: it is the same
+device behaviour, now reported instead of delivered as a wrong image. Scope: this one camera, grabs right after a
+cancelled grab, intermittent (2 of 8 rounds per version). Why the device cuts the next grab's block was not
+measured. Figures and raw logs are the consumer's (its `cvinspect-0290-cutloop` run); see its records.
+
 `PixelFormatInfo.FrameBytes` is the single definition of that and `GvspImageLeader.ImageBytes` routes
 through it, so the receiver sizes a frame the way the device does. Where a line is not a whole number of
 bytes and there is no line padding there is no stride at all, and saying so is part of the fix:

docs/genapi-model.md

@@ -86,7 +86,7 @@ all four float kinds → `Float`, `Node`/`Unknown` → `Unknown`).
 | `IsStreamable` | bool | `Streamable` | default false |
 | `PErrors` | IReadOnlyList\<string\> | `pError`* | |
 | `IsDeprecated` | bool | `IsDeprecated` | default false |
-| `PollingTimeMs` | long? | `PollingTime` | register nodes: treat reads as NoCache; Command: completion polling |
+| `PollingTimeMs` | long? | `PollingTime` | only its presence is used, never the interval: register nodes treat reads as NoCache; a Command's `IsDone` re-reads `pValue` (GevSharp's own rule). The caller picks the polling interval |
 | `PSelected` | IReadOnlyList\<string\> | `pSelected`* | accepted on any kind; meaningful on Integer kinds, Enumeration, Boolean. `pSelecting` is derived by the runtime |
 
 `MergePriority`/`ExposeStatic` attributes and `<Extension>` are ignored.

docs/protocol-notes.md

@@ -50,7 +50,9 @@ See `GvbsAddr`. Highlights:
 - `0x0200` first URL (512), `0x0400` second URL (512) — camera XML location.
 - `0x0934` GVCP capability bits (bit2 packet resend, bit5 pending ack, bit29 heartbeat disable, …),
   `0x0938` heartbeat timeout (ms), `0x093C/0x0940` timestamp tick frequency (Hz, 64-bit),
-  `0x0944` timestamp control (write 2 = reset, 1 = latch), `0x0948/0x094C` latched timestamp.
+  `0x0944` timestamp control (write 1 = reset, 2 = latch — the values real device descriptions put in
+  `GevTimestampControlReset`/`GevTimestampControlLatch`; an earlier revision of this line had them swapped),
+  `0x0948/0x094C` latched timestamp.
 - `0x0A00` CCP: 1 = exclusive, 2 = control, 4 = control switchover enable; 0 = open. Writing CCP requires
   no privilege when the register is 0; writes from a non-controlling host return `ACCESS_DENIED (0x8006)`.
   `0x0A04`/`0x0A14` primary application port/IP — the socket of whoever holds control, which answers
@@ -243,7 +245,10 @@ into a node map is a later milestone.
   `<pSelected>` on selector features (the selected features are those listed).
 - Guards: `<pIsImplemented>`, `<pIsAvailable>`, `<pIsLocked>` (Integer/Boolean/SwissKnife nodes: non-zero = true),
   `<ImposedAccessMode>`, `<pInvalidator>` (nodes whose write invalidates this node's cache), `<Streamable>`.
-- Commands: `<CommandValue>` / `<pCommandValue>` written to `<pValue>`; `<PollingTime>` marks self-clearing bits.
+- Commands: `<CommandValue>` / `<pCommandValue>` written to `<pValue>`. `<PollingTime>` on a Command is *read by
+  GevSharp* as marking a self-clearing bit that `IsDone` may poll — GevSharp's own reading, not a rule taken from a
+  primary source (none checked). Descriptions often leave it out, also on commands that take time to finish
+  (a user-set load), and others put it on exactly those commands.
 - Booleans: `<OnValue>` / `<OffValue>` (default 1 / 0).
 - Strings: `<StringReg>` fixed `Length`, `<String>` literal or `pValue`.
 - Floats: `<FloatReg>` Length 4/8 IEEE; `<Converter>`; `<Float>` with `Min/Max/Inc/Unit/Representation/DisplayNotation/DisplayPrecision`.