feat: add Workflow Insight plugin

.github/scripts/maven_publish.sh

@@ -45,5 +45,6 @@ echo "=== Step 3: Upload to Sonatype Central Portal ==="
 mvn clean deploy -s "${SETTINGS_FILE}" -pl sdk -P publishing -DskipTests --no-transfer-progress
 mvn clean deploy -s "${SETTINGS_FILE}" -pl sdk-testing -P publishing -DskipTests --no-transfer-progress
 mvn clean deploy -s "${SETTINGS_FILE}" -pl otel-plugin -P publishing -DskipTests --no-transfer-progress
+mvn clean deploy -s "${SETTINGS_FILE}" -pl insight-plugin -P publishing -DskipTests --no-transfer-progress
 
 echo "=== Release ${RELEASE_VERSION} uploaded successfully; review and publish it in Sonatype Central Portal. ==="

.github/workflows/build.yml

@@ -28,6 +28,7 @@ on:
       - 'sdk/**'
       - 'sdk-testing/**'
       - 'sdk-integration-tests/**'
+      - 'insight-plugin/**'
       - 'examples/**'
       - 'pom.xml'
   push:
@@ -40,6 +41,7 @@ on:
       - 'sdk/**'
       - 'sdk-testing/**'
       - 'sdk-integration-tests/**'
+      - 'insight-plugin/**'
       - 'examples/**'
       - 'pom.xml'
 

.github/workflows/publish_maven.yml

@@ -92,6 +92,7 @@ jobs:
             "sdk/target/aws-durable-execution-sdk-java-${RELEASE_VERSION}.jar" \
             "sdk-testing/target/aws-durable-execution-sdk-java-testing-${RELEASE_VERSION}.jar" \
             "otel-plugin/target/aws-durable-execution-sdk-java-plugin-otel-${RELEASE_VERSION}.jar" \
+            "insight-plugin/target/aws-durable-execution-sdk-java-plugin-insight-${RELEASE_VERSION}.jar" \
             --clobber
 
       - name: Checkout default branch

RELEASE.md

@@ -43,9 +43,9 @@ The publication workflow:
 
 1. Verifies that the tag is a semantic version, points to a commit on the
    default branch, and matches the Maven version in the tagged POM.
-2. Builds, signs, and uploads the SDK, testing library, and OpenTelemetry plugin
-   to Sonatype Central Portal.
-3. Uploads the three JARs to the existing GitHub release.
+2. Builds, signs, and uploads the SDK, testing library, OpenTelemetry plugin,
+   and Workflow Insight plugin to Sonatype Central Portal.
+3. Uploads the four JARs to the existing GitHub release.
 4. Opens a pull request for the next development version. A final release
    increments the patch version, so `2.1.1` produces `2.1.2-SNAPSHOT`. A
    prerelease keeps the same base version, so `2.1.1-rc1` produces
@@ -56,7 +56,8 @@ After **Publish Maven Release** succeeds:
 1. Open [Publishing Deployments](https://central.sonatype.com/publishing/deployments)
    in Sonatype Central Portal.
 2. Find the deployments for the release version and verify that they contain
-   the expected SDK, testing library, and OpenTelemetry plugin artifacts.
+   the expected SDK, testing library, OpenTelemetry plugin, and Workflow Insight
+   plugin artifacts.
 3. Click **Publish** for each deployment and wait for publication to complete.
    The workflow uses `autoPublish=false`, so this manual action is required.
 4. Confirm that the GitHub release contains the expected JARs and that the

insight-plugin/README.md

@@ -0,0 +1,65 @@
+# Workflow Insight Plugin (preview)
+
+Instrumentation plugin for the AWS Lambda Durable Execution Java SDK that emits a curated,
+per-execution **Workflow Insight record** to one or more pluggable exporters. It ports the
+JavaScript `workflowInsight()` contract (canonical record schema `1.0`) to the Java plugin hook
+surface.
+
+> **Preview API.** Every public type is annotated `@Deprecated` to signal it is experimental and
+> may change or be removed in a future release.
+
+## Usage
+
+```java
+DurableConfig config = DurableConfig.builder()
+    .withPlugins(WorkflowInsight.workflowInsight(WorkflowInsightConfig.builder()
+        .samplingRate(1.0)
+        .emitMode(WorkflowInsightConfig.EmitMode.ON_COMPLETE)     // ON_COMPLETE | ON_CHANGE | ON_FAILURE
+        .operationDetail(WorkflowInsightConfig.OperationDetail.TOP_LEVEL) // TOP_LEVEL | FULL_TREE
+        .content(ContentConfig.builder()
+            .input(true).output(true).includeErrors(true)
+            .addOverride(OperationOverride.withResult("compute", r -> r))
+            .build())
+        .addExporter(S3Exporter.builder().bucket("my-bucket").build())
+        .build()))
+    .build();
+```
+
+Exporters: `LambdaLogExporter` (default; writes the `operationsByName` map to stdout →
+CloudWatch), `S3Exporter` (canonical `operations` array, one object per execution),
+`CloudWatchLogsExporter` (PutLogEvents to a specific log group, `operationsByName` map). Implement
+`InsightExporter` for custom sinks.
+
+## Design
+
+- **Snapshot-based, not accumulated.** Each record is built directly from the current-invocation
+  operation snapshot the SDK provides — `InvocationInfo.operations()` at start / operation change
+  and `InvocationEndInfo.operations()` at end. Execution input/output come from
+  `InvocationInfo.executionInput()` / `InvocationEndInfo.executionResult()`, and per-operation
+  results from `OperationChangeItemInfo.result()` (all surfaced by SDK PR #618). There is no global
+  "current ARN" or cross-hook operation accumulation.
+- **Per-execution state keyed by execution ARN** holds only the stable start time, parsed ARN,
+  cached input, and the one-time deterministic sampling decision. State is **preserved across
+  non-terminal (PENDING/RETRYING) invocations** so suspend/resume keeps a single stable start time
+  and correct duration, and is removed **only** once the execution is terminal.
+- **Deterministic sampling.** FNV-1a-32 over the execution ARN mapped into `[0,1)`, identical to
+  the JS implementation, so a resumed execution always reaches the same in/out decision.
+- **Emission modes.** `ON_COMPLETE` emits one terminal record; `ON_FAILURE` emits only on terminal
+  failure; `ON_CHANGE` emits at invocation start, on every operation change, and at invocation end
+  (matching JS). Non-terminal statuses map to `RUNNING`.
+- **Operation filtering** mirrors JS: the `EXECUTION` pseudo-operation and unnamed operations are
+  dropped; `TOP_LEVEL` detail drops any operation with a `parentId`; an `OperationOverride.exclude`
+  drops by name. Operation `result` is included only when an `OperationOverride.withResult`
+  transform opts in — the checkpointed JSON is parsed before the transform, falling back to the raw
+  string, and a throwing transform omits the field.
+- **Per-exporter size truncation** (`Truncation`) drops, in order: operation results oldest-first,
+  then whole operations oldest-first, then execution input, then output — setting `truncated`,
+  `droppedOperations`, `droppedInput`, `droppedOutput` as applicable. The size is measured against
+  the exact shape each exporter emits (its `render`).
+- **Exporter isolation.** Every exporter is truncated, exported, and flushed independently; a
+  failing exporter is logged and never blocks the others or the execution.
+
+## Conformance
+
+Validated against the Workflow Insight conformance suite behaviors `insight-1 … insight-18`
+(PR #73 Java examples). See the module tests for the behavior mapping.