From de4571da4b262b458a32b386e62d4f102dca62cf Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 22:27:50 -0400
Subject: [PATCH] docs: document sdk dedupe and group contracts

---
 src/plugin-sdk/group-access.ts      | 6 ++++++
 src/plugin-sdk/persistent-dedupe.ts | 6 ++++++
 src/plugin-sdk/runtime-logger.ts    | 2 ++
 3 files changed, 14 insertions(+)

diff --git a/src/plugin-sdk/group-access.ts b/src/plugin-sdk/group-access.ts
index c3c6afd548f0..91d440e79b2d 100644
--- a/src/plugin-sdk/group-access.ts
+++ b/src/plugin-sdk/group-access.ts
@@ -9,34 +9,40 @@ import type { GroupPolicy } from "../config/types.base.js";
 export { resolveOpenProviderRuntimeGroupPolicy };
 export type { GroupPolicy };
 
+/** Reason code returned when evaluating a sender against group policy. */
 export type SenderGroupAccessReason =
   | "allowed"
   | "disabled"
   | "empty_allowlist"
   | "sender_not_allowlisted";
+/** Sender-level group access decision plus the effective group policy. */
 export type SenderGroupAccessDecision = {
   allowed: boolean;
   groupPolicy: GroupPolicy;
   providerMissingFallbackApplied: boolean;
   reason: SenderGroupAccessReason;
 };
+/** Reason code returned when evaluating a configured group route. */
 export type GroupRouteAccessReason =
   | "allowed"
   | "disabled"
   | "empty_allowlist"
   | "route_not_allowlisted"
   | "route_disabled";
+/** Route-level group access decision plus the effective group policy. */
 export type GroupRouteAccessDecision = {
   allowed: boolean;
   groupPolicy: GroupPolicy;
   reason: GroupRouteAccessReason;
 };
+/** Reason code returned when evaluating a precomputed allowlist match. */
 export type MatchedGroupAccessReason =
   | "allowed"
   | "disabled"
   | "missing_match_input"
   | "empty_allowlist"
   | "not_allowlisted";
+/** Matched-input group access decision plus the effective group policy. */
 export type MatchedGroupAccessDecision = {
   allowed: boolean;
   groupPolicy: GroupPolicy;
diff --git a/src/plugin-sdk/persistent-dedupe.ts b/src/plugin-sdk/persistent-dedupe.ts
index 0e1685b3bb50..6e90c8f9db8e 100644
--- a/src/plugin-sdk/persistent-dedupe.ts
+++ b/src/plugin-sdk/persistent-dedupe.ts
@@ -7,6 +7,7 @@ import { readJsonFileWithFallback, writeJsonFileAtomically } from "./json-store.
 
 type PersistentDedupeData = Record<string, number>;
 
+/** Configuration for a disk-backed dedupe namespace cache. */
 export type PersistentDedupeOptions = {
   /** Milliseconds a recorded key remains recent; `0` keeps keys until cache pruning. */
   ttlMs: number;
@@ -20,6 +21,7 @@ export type PersistentDedupeOptions = {
   onDiskError?: (error: unknown) => void;
 };
 
+/** Per-call options used when checking or recording a dedupe key. */
 export type PersistentDedupeCheckOptions = {
   /** Logical bucket for the key; omitted/blank values use `global`. */
   namespace?: string;
@@ -29,6 +31,7 @@ export type PersistentDedupeCheckOptions = {
   onDiskError?: (error: unknown) => void;
 };
 
+/** Disk-backed dedupe guard that records recently seen keys per namespace. */
 export type PersistentDedupe = {
   /** Returns true only when the key was not recently seen and was recorded for future checks. */
   checkAndRecord: (key: string, options?: PersistentDedupeCheckOptions) => Promise<boolean>;
@@ -42,11 +45,13 @@ export type PersistentDedupe = {
   memorySize: () => number;
 };
 
+/** Claim attempt result for dedupe flows that need in-flight ownership. */
 export type ClaimableDedupeClaimResult =
   | { kind: "claimed" }
   | { kind: "duplicate" }
   | { kind: "inflight"; pending: Promise<boolean> };
 
+/** Options for a claimable dedupe guard, either persistent or memory-only. */
 export type ClaimableDedupeOptions =
   | {
       ttlMs: number;
@@ -65,6 +70,7 @@ export type ClaimableDedupeOptions =
       onDiskError?: undefined;
     };
 
+/** Dedupe guard that lets one caller own a key while others wait or detect duplicates. */
 export type ClaimableDedupe = {
   /** Starts ownership of a key, reports duplicates, or returns the active claim's pending result. */
   claim: (
diff --git a/src/plugin-sdk/runtime-logger.ts b/src/plugin-sdk/runtime-logger.ts
index 0faf906e1eba..a268e0cb9260 100644
--- a/src/plugin-sdk/runtime-logger.ts
+++ b/src/plugin-sdk/runtime-logger.ts
@@ -42,6 +42,7 @@ export function resolveRuntimeEnv(params: {
   logger: LoggerLike;
   exitError?: (code: number) => Error;
 }): RuntimeEnv;
+/** @deprecated Import from `openclaw/plugin-sdk/runtime` instead. */
 export function resolveRuntimeEnv(params: {
   runtime?: undefined;
   logger: LoggerLike;
@@ -61,6 +62,7 @@ export function resolveRuntimeEnvWithUnavailableExit(params: {
   logger: LoggerLike;
   unavailableMessage?: string;
 }): RuntimeEnv;
+/** @deprecated Import from `openclaw/plugin-sdk/runtime` instead. */
 export function resolveRuntimeEnvWithUnavailableExit(params: {
   runtime?: undefined;
   logger: LoggerLike;