raindrop-ai 0.7.0-otelv2 → 0.7.1

package/README.md

@@ -2,6 +2,31 @@
 
 Primary Raindrop JavaScript SDK for event tracking, AI event ingestion, self-diagnostics, and tracing helpers.
 
+## Application commit reporting
+
+The SDK adds `raindrop.app.commit_sha` when the running application's revision is available. It never substitutes the SDK revision or changes existing SDK/release fields. Set `appGit` on the client for explicit build identity or a selected application checkout:
+
+```ts
+const raindrop = new Raindrop({
+  writeKey: process.env.RAINDROP_WRITE_KEY,
+  appGit: {
+    commitSha: process.env.APP_BUILD_SHA,
+    // commitDirty: false, // only if the build knows this fact
+    // branch: "customer-defined-label", // explicit ordinary property
+    // detectBranch: true, // new automatic branch reporting is opt-in
+    // sourceDirectory: "/path/to/the/agent", // not the observer or SDK repository
+  },
+});
+```
+
+Per-operation canonical properties override defaults without mutation, including null/empty values. `appGit: false` disables defaults; `{ autoDetect: false }` disables discovery but retains explicit options/environment. Explicit env names are `RAINDROP_COMMIT_SHA`, `RAINDROP_COMMIT_DIRTY`, `RAINDROP_BRANCH`; controls are `RAINDROP_GIT_AUTO_DETECT`, `RAINDROP_GIT_DETECT_BRANCH`, and `RAINDROP_GIT_SOURCE_DIRECTORY`.
+
+Default Node discovery uses reliable application deployment metadata, then background Git from the application cwd, then contextual CI. Full40/64-character Git hashes are accepted. Lookup never blocks track/begin/flush/close; its total deadline is one second, and absent/pending metadata is omitted. Provide the SHA explicitly for deterministic first-event reporting or short-lived processes. Source directories captured at client creation do not follow later `process.chdir()` calls. Unknown dirty state stays unknown, never clean by assumption.
+
+Replay create/claim/started reuse the existing `commit_sha`, `commit_branch`, and `commit_dirty` fields and the same frozen candidate snapshot. Source dataset properties remain source lineage; the SDK does not copy their Git identity into candidate defaults. Legacy replay branch reporting is retained from background discovery, without enabling the ordinary branch property. A pending lookup may leave an entire replay unattributed; there is no late backfill or wait. Supply `appGit` on the client or at create/claim, before the handle is run; `runReplay` does not offer a source override. For local Git discovery, initialize a client beforehand: a `sourceDirectory` supplied only to create/claim cannot finish background discovery before that operation takes its immediate snapshot. Supply a known SHA for deterministic first-operation identity. SHA metadata is report-only and does not select a checkout target.
+
+Flat replay metadata accepts full 40/64-hex revision strings and trims surrounding whitespace without changing hex case. Its branch value is trimmed and must be nonempty and at most 400 characters; unsupported branch values are omitted so optional metadata cannot prevent a replay from running. Ordinary application properties retain their exact supplied values. This report-only metadata is separate from checkout-target validation.
+
 ## Install
 
 ```bash