@openclaw/plugin-inspector 0.3.12 → 0.3.14

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
-## Unreleased
+## 0.3.14 - 2026-06-11
+
+### Changed
+
+- Flag deprecated `loadSessionStore(...)` whole-store session helper usage as an author-facing deprecation warning while keeping speculative transcript-identity migration rules out of default inspection. Thanks @jalehman.
+
+## 0.3.13 - 2026-06-09
+
+### Changed
+
+- Add `authorRemediation.summary` and `authorRemediation.docsUrl` guidance to author-facing compatibility issues and Markdown reports.
+- Add `--author-facing` for `check`, `ci`, and `batch` reports while keeping default output complete for internal coverage findings.
+- Replace the recent `--include-inspector-gaps` option with a clear error pointing to `--author-facing`.
 
 ## 0.3.12 - 2026-06-09
 

package/README.md

@@ -187,7 +187,7 @@ Common options:
 | `--mock-sdk` / `--sdk mock` | Use generated SDK and external-package mocks for runtime capture. |
 | `--real-sdk` / `--sdk real` | Use installed real SDK dependencies instead of mocks. |
 | `--allow-execute` | Permit commands that import plugin code. |
-| `--include-inspector-gaps` | Include maintainer-facing scanner coverage gaps in `check`, `ci`, and `batch` output. |
+| `--author-facing` | Limit `check`, `ci`, and `batch` reports to findings with `authorRemediation` guidance. |
 | `--json` | Print machine-readable JSON to stdout. |
 | `--sarif [path]` | Write SARIF from `check` or `inspect`; `ci` enables this by default. |
 | `--junit [path]` | Write JUnit XML from `check` or `inspect`; `ci` enables this by default. |
@@ -299,7 +299,7 @@ Important report sections:
 | `status` | `pass` unless hard breakages exist. |
 | `summary` | Counts for fixtures, breakages, warnings, suggestions, issues, issue classes, and contract probes. |
 | `targetOpenClaw` | Status and public compatibility data read from the optional OpenClaw checkout. |
-| `fixtures` | Per-plugin metadata, hooks, registrations, manifest contracts, package data, and SDK imports. |
+| `fixtures` | Per-plugin metadata, hooks, registrations, manifest contracts, package data, SDK imports, and SDK deprecation evidence. |
 | `breakages` | Blocking compatibility failures. |
 | `warnings` / `suggestions` | Non-blocking compatibility findings. |
 | `issues` | Normalized issue rows with severity and class. |
@@ -307,9 +307,13 @@ Important report sections:
 | `logs` | Informational inventory and coverage rows. |
 | `decisions` | Maintainer-facing follow-up or compatibility-policy decisions. |
 
-Author-facing `check`, `ci`, and `batch` output hides inspector gaps by default
-because they are scanner coverage backlog, not plugin-author fixes. Pass
-`--include-inspector-gaps` for Crabpot-style maintainer coverage reports.
+Default `check`, `ci`, and `batch` reports include both author-facing and
+internal findings. Pass `--author-facing` when producing plugin-author output;
+that filtered view includes only findings with `authorRemediation.summary` and
+`authorRemediation.docsUrl`.
+Current author-facing deprecation warnings include deprecated SDK helpers such
+as `loadSessionStore(...)` when a plugin still depends on the legacy whole-store
+session shape.
 
 ## CI Policy And Shared Reporting Primitives
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",

package/src/advanced.js

@@ -77,6 +77,7 @@ export {
   classifyIssueFinding,
   deprecatedCompatRecords,
   issueId,
+  isAuthorFacingFinding,
   issueMetadata,
   issueMetadataByCode,
   knownIssueCodes,

package/src/api.js

@@ -43,8 +43,8 @@ export async function loadPluginConfig(options = {}) {
 export async function inspectPluginRoot(options = {}) {
   const config = await loadPluginConfig(options);
   return inspectCompatibilityFixtureSet(config, {
+    authorFacing: options.authorFacing,
     generatedAt: options.generatedAt,
-    includeInspectorGaps: options.includeInspectorGaps,
     openclawPath: options.openclawPath,
     executionResults: options.executionResults,
     targetOpenClaw: options.targetOpenClaw,
@@ -59,8 +59,8 @@ export async function inspectFixtureSetConfig(options = {}) {
 export async function inspectCompatibilityFixtureSetConfig(options = {}) {
   const config = await loadFixtureSetConfig(options);
   return inspectCompatibilityFixtureSet(config, {
+    authorFacing: options.authorFacing,
     generatedAt: options.generatedAt,
-    includeInspectorGaps: options.includeInspectorGaps,
     openclawPath: options.openclawPath,
     executionResults: options.executionResults,
     targetOpenClaw: options.targetOpenClaw,
@@ -114,8 +114,8 @@ export async function buildFixtureSetColdImportReadiness(options = {}) {
   const report =
     options.report ??
     (await inspectCompatibilityFixtureSet(config, {
+      authorFacing: options.authorFacing,
       generatedAt: options.generatedAt,
-      includeInspectorGaps: options.includeInspectorGaps,
       openclawPath: options.openclawPath,
       executionResults: options.executionResults,
       targetOpenClaw: options.targetOpenClaw,
@@ -147,8 +147,8 @@ export async function buildFixtureSetWorkspacePlan(options = {}) {
   const report =
     options.report ??
     (await inspectCompatibilityFixtureSet(config, {
+      authorFacing: options.authorFacing,
       generatedAt: options.generatedAt,
-      includeInspectorGaps: options.includeInspectorGaps,
       openclawPath: options.openclawPath,
       executionResults: options.executionResults,
       targetOpenClaw: options.targetOpenClaw,

package/src/batch.js

@@ -108,9 +108,9 @@ async function inspectBatchPlugin(pluginRoot, options) {
   try {
     const { report } = await runPluginCheck({
       allowExecution: options.allowExecution,
+      authorFacing: options.authorFacing,
       capture: options.capture,
       configPath: options.configPath,
-      includeInspectorGaps: options.includeInspectorGaps,
       mockSdk: options.mockSdk,
       openclawPath: options.openclawPath,
       outDir: options.outDir,
@@ -148,17 +148,20 @@ async function inspectBatchPlugin(pluginRoot, options) {
 }
 
 function normalizeReportFindings(report) {
-  return [
-    ...(report.breakages ?? []).map((finding) => normalizeFinding(finding, "error")),
-    ...(report.issues ?? []).map((finding) =>
-      normalizeFinding(
-        finding,
-        finding.status === "blocking" || finding.severity === "P0" ? "error" : "warning",
-      ),
+  const issueFindings = (report.issues ?? []).map((finding) =>
+    normalizeFinding(
+      finding,
+      finding.status === "blocking" || finding.severity === "P0" ? "error" : "warning",
     ),
+  );
+  const issueKeys = new Set(issueFindings.map(findingKey));
+  const rawFindings = [
+    ...(report.breakages ?? []).map((finding) => normalizeFinding(finding, "error")),
     ...(report.warnings ?? []).map((finding) => normalizeFinding(finding, "warning")),
     ...(report.suggestions ?? []).map((finding) => normalizeFinding(finding, "warning")),
-  ];
+  ].filter((finding) => !issueKeys.has(findingKey(finding)));
+
+  return [...issueFindings, ...rawFindings];
 }
 
 function normalizeFinding(finding, kind) {
@@ -169,9 +172,18 @@ function normalizeFinding(finding, kind) {
     issueClass: finding.issueClass,
     message: finding.message ?? finding.title ?? "See plugin report.",
     evidence: finding.evidence,
+    ...(finding.authorRemediation ? { authorRemediation: finding.authorRemediation } : {}),
   };
 }
 
+function findingKey(finding) {
+  return [
+    finding.fixture ?? "",
+    finding.code ?? "",
+    ...(Array.isArray(finding.evidence) ? finding.evidence : []),
+  ].join("\n");
+}
+
 function findingFrequencyRows(entries) {
   const byCode = new Map();
   for (const entry of entries) {

package/src/cli.js

@@ -64,7 +64,7 @@ async function runBatch(commandArgs) {
   const json = commandArgs.includes("--json");
   const check = commandArgs.includes("--check");
   const keepPluginReports = commandArgs.includes("--keep-plugin-reports");
-  const includeInspectorGaps = commandArgs.includes("--include-inspector-gaps");
+  const authorFacing = readAuthorFacingFlag(commandArgs);
   if (!inputDir) {
     throw new Error("batch requires a folder of plugin roots");
   }
@@ -73,7 +73,7 @@ async function runBatch(commandArgs) {
     outDir,
     openclawPath,
     concurrency,
-    includeInspectorGaps,
+    authorFacing,
     keepPluginReports,
   });
 
@@ -110,12 +110,12 @@ async function runCheck(commandArgs) {
   const mockSdk = readMockSdkFlag(commandArgs);
   const allowExecution = readAllowExecutionFlag(commandArgs);
   const ciOutputs = readCiOutputFlags(commandArgs);
-  const includeInspectorGaps = commandArgs.includes("--include-inspector-gaps");
+  const authorFacing = readAuthorFacingFlag(commandArgs);
   const { report, paths } = await runPluginCheck({
     allowExecution,
+    authorFacing,
     capture,
     configPath,
-    includeInspectorGaps,
     mockSdk,
     openclawPath,
     outDir,
@@ -168,12 +168,18 @@ async function runInit(commandArgs) {
 async function runReport(command, commandArgs) {
   const configPath = readFlag(commandArgs, "--config");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
+  const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
   const check = commandArgs.includes("--check") || command === "ci";
   const json = commandArgs.includes("--json");
   const ciOutputs = readCiOutputFlags(commandArgs);
+  const authorFacing = readAuthorFacingFlag(commandArgs);
   const config = await loadInspectorConfig(configPath);
-  const report = await inspectFixtureSet(config);
-  const paths = await writeReport(report, { outDir });
+  const report = authorFacing
+    ? await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath })
+    : await inspectFixtureSet(config);
+  const paths = authorFacing
+    ? await writeCompatibilityReport(report, { cwd: config.rootDir, outDir })
+    : await writeReport(report, { outDir });
   await writeCiOutputArtifacts(report, {
     ...ciOutputs,
     cwd: path.dirname(paths.jsonPath),
@@ -201,12 +207,12 @@ async function runCi(commandArgs) {
   const mockSdk = readMockSdkFlag(commandArgs);
   const allowExecution = readAllowExecutionFlag(commandArgs);
   const ciOutputs = readCiOutputFlags(commandArgs, { defaultEnabled: true });
-  const includeInspectorGaps = commandArgs.includes("--include-inspector-gaps");
+  const authorFacing = readAuthorFacingFlag(commandArgs);
   const { report, reportDir } = await runCiCompatibilityReport({
     allowExecution,
+    authorFacing,
     capture,
     configPath,
-    includeInspectorGaps,
     mockSdk,
     openclawPath,
     outDir,
@@ -245,9 +251,9 @@ async function runCi(commandArgs) {
 
 async function runCiCompatibilityReport({
   allowExecution,
+  authorFacing,
   capture,
   configPath,
-  includeInspectorGaps,
   mockSdk,
   openclawPath,
   outDir,
@@ -255,7 +261,7 @@ async function runCiCompatibilityReport({
 }) {
   if (configPath) {
     const config = await loadInspectorConfig(configPath, { cwd: pluginRoot });
-    const report = await inspectCompatibilityFixtureSet(config, { includeInspectorGaps, openclawPath });
+    const report = await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath });
     await writeCompatibilityReport(report, { cwd: config.rootDir, outDir });
     return {
       report,
@@ -265,8 +271,8 @@ async function runCiCompatibilityReport({
 
   const { report } = await runPluginCheck({
     allowExecution,
+    authorFacing,
     capture,
-    includeInspectorGaps,
     mockSdk,
     openclawPath,
     outDir,
@@ -373,6 +379,15 @@ function readAllowExecutionFlag(commandArgs) {
   return commandArgs.includes("--allow-execute");
 }
 
+function readAuthorFacingFlag(commandArgs) {
+  if (commandArgs.includes("--include-inspector-gaps")) {
+    throw new Error(
+      "--include-inspector-gaps has been replaced by --author-facing; default output now includes internal findings.",
+    );
+  }
+  return commandArgs.includes("--author-facing");
+}
+
 function renderCiTextSummary(summary) {
   return [
     `Status: ${summary.status.toUpperCase()}`,
@@ -437,18 +452,18 @@ function printHelp() {
 
 Usage:
   plugin-inspector
-  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--include-inspector-gaps] [--json]
+  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json]
   plugin-inspector config [--plugin-root <path>] [--config <path>] [--json]
   plugin-inspector init [--plugin-root <path>] [--config <path>] [--ci] [--scripts] [--package-manager npm|pnpm|yarn|bun] [--dry-run] [--json] [--force]
-  plugin-inspector report --config <path> [--out <dir>] [--check] [--json]
-  plugin-inspector batch <folder> [--out <dir>] [--openclaw <path>] [--no-openclaw] [--concurrency <n>] [--keep-plugin-reports] [--include-inspector-gaps] [--check] [--json]
-  plugin-inspector inspect [--plugin-root <path>] [--config <path>] [--out <dir>] [--check] [--json] [--sarif [path]] [--junit [path]] [--allow-execute]
-  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--include-inspector-gaps] [--json] [--no-sarif] [--no-junit]
+  plugin-inspector report --config <path> [--out <dir>] [--openclaw <path>] [--no-openclaw] [--author-facing] [--check] [--json]
+  plugin-inspector batch <folder> [--out <dir>] [--openclaw <path>] [--no-openclaw] [--concurrency <n>] [--keep-plugin-reports] [--author-facing] [--check] [--json]
+  plugin-inspector inspect [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--author-facing] [--check] [--json] [--sarif [path]] [--junit [path]] [--allow-execute]
+  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json] [--no-sarif] [--no-junit]
   plugin-inspector capture <entrypoint> [--mock-sdk|--real-sdk] [--allow-execute] [--plugin-root <path>] [--output <path>]
 
 Default check runs from the current plugin root and writes reports/ unless --out is set.
 CI writes SARIF and JUnit artifacts by default; check/inspect can write them with --sarif and --junit.
 Runtime capture is opt-in because it imports plugin code; use --runtime with --allow-execute or PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1.
-Inspector coverage gaps are hidden by default; pass --include-inspector-gaps for maintainer coverage reports.
+Default output includes author-facing and internal findings; pass --author-facing to show only findings with author remediation docs.
 `);
 }

package/src/compatibility-report.js

@@ -250,10 +250,23 @@ function issueBlock(issue, options) {
     `  - state: ${issueState(issue)}`,
     "  - evidence:",
     ...evidenceList(issue.evidence, options).map((item) => `    - ${item}`),
+    ...remediationList(issue),
     ...runtimeCoverageList(issue, options),
   ].join("\n");
 }
 
+function remediationList(issue) {
+  const remediation = issue.authorRemediation;
+  if (!remediation?.summary) {
+    return [];
+  }
+  return [
+    "  - author remediation:",
+    `    - ${remediation.summary}`,
+    `    - docs: ${remediation.docsUrl}`,
+  ];
+}
+
 function issueState(issue) {
   const flags = [
     issue.status,

package/src/fixture-summary.js

@@ -49,6 +49,7 @@ export async function buildCompatibilityFixtureReport({ fixture, inspection, che
     packages: packageSummaries,
     sdkImports,
     sdkImportDetails: inspection.sdkImports ?? [],
+    sdkDeprecations: inspection.sdkDeprecations ?? [],
   };
 }
 
@@ -496,6 +497,7 @@ export function classifyCompatibilityFixture({ fixture, inspection, fixtureRepor
   logs.push(...packageContracts.logs);
   decisions.push(...packageContracts.decisions);
   classifySecurityManifestCoverage({ fixture, fixtureReport, warnings, decisions });
+  classifySdkDeprecations({ fixture, inspection, fixtureReport, warnings, decisions });
 
   for (const pluginManifest of fixtureReport.pluginManifests) {
     const providerAuthKeys = Object.keys(pluginManifest.providerAuthEnvVars ?? {});
@@ -702,6 +704,34 @@ export function classifyCompatibilityFixture({ fixture, inspection, fixtureRepor
   return { warnings, suggestions, logs, decisions };
 }
 
+function classifySdkDeprecations({ fixture, inspection, fixtureReport, warnings, decisions }) {
+  const grouped = new Map();
+  for (const finding of fixtureReport.sdkDeprecations ?? inspection.sdkDeprecations ?? []) {
+    const existing = grouped.get(finding.code) ?? [];
+    existing.push(finding);
+    grouped.set(finding.code, existing);
+  }
+
+  for (const [code, findings] of grouped) {
+    const first = findings[0];
+    warnings.push({
+      fixture: fixture.id,
+      code,
+      level: "warning",
+      message: first.message,
+      evidence: findings.map((finding) => `${finding.surface} @ ${finding.ref}`),
+    });
+    decisions.push({
+      fixture: fixture.id,
+      decision: "core-compat-adapter",
+      seam: "session-store",
+      action:
+        "Keep loadSessionStore compatibility active while plugin authors migrate to row-scoped session helpers.",
+      evidence: findings.map((finding) => finding.ref).join(", "),
+    });
+  }
+}
+
 function classifySecurityManifestCoverage({ fixture, fixtureReport, warnings, decisions }) {
   for (const securityManifest of fixtureReport.securityManifests ?? []) {
     warnings.push({

package/src/index.js

@@ -217,7 +217,7 @@ export {
   validateImportLoopProfile,
   writeImportLoopProfile,
 } from "./import-loop-profile.js";
-export { classifyIssueFinding, issueId, knownIssueCodes } from "./issues.js";
+export { classifyIssueFinding, issueId, isAuthorFacingFinding, knownIssueCodes } from "./issues.js";
 export { inspectFixtureSet, inspectPlugin, inspectSourceText } from "./inspector.js";
 export { openClawTargetPathCandidates, readOpenClawTargetSurface } from "./openclaw-target.js";
 export {

package/src/inspector.js

@@ -10,6 +10,7 @@ import { fixtureCheckoutPath, fixtureSourceRoot } from "./config.js";
 import { buildCompatibilityFixtureReport } from "./fixture-summary.js";
 import { readOpenClawTargetSurface } from "./openclaw-target.js";
 import { buildCompatibilityReport, buildReport } from "./report.js";
+import { inspectSdkDeprecations } from "./sdk-deprecation-rules.js";
 
 const execFileAsync = promisify(execFile);
 const registrationEquivalents = new Map([
@@ -35,9 +36,9 @@ export async function inspectCompatibilityFixtureSet(config, options = {}) {
     config,
     inspections,
     failures,
+    authorFacing: options.authorFacing,
     generatedAt: options.generatedAt,
     executionResults: options.executionResults,
-    includeInspectorGaps: options.includeInspectorGaps,
     targetOpenClaw,
     buildFixtureReport: ({ fixture, inspection }) =>
       buildCompatibilityFixtureReport({
@@ -104,6 +105,7 @@ export async function inspectPlugin(fixture, options = {}) {
   const hookDetails = [];
   const registrationDetails = [];
   const sdkImportDetails = [];
+  const sdkDeprecationDetails = [];
 
   for (const filePath of files) {
     const text = await readFile(filePath, "utf8");
@@ -121,6 +123,9 @@ export async function inspectPlugin(fixture, options = {}) {
     for (const sdkImport of sourceInspection.sdkImports) {
       sdkImportDetails.push(sdkImport);
     }
+    for (const sdkDeprecation of sourceInspection.sdkDeprecations) {
+      sdkDeprecationDetails.push(sdkDeprecation);
+    }
   }
 
   const manifestInspection = await readManifestContracts(config, checkoutPath, sourceRoot);
@@ -140,6 +145,7 @@ export async function inspectPlugin(fixture, options = {}) {
     packageErrors: packageInspection.errors,
     packageEntrypoints: packageInspection.entrypoints,
     sdkImports: uniqueDetails(sdkImportDetails),
+    sdkDeprecations: uniqueSdkDeprecations(sdkDeprecationDetails),
     sourceFiles: files.map((filePath) => path.relative(config.rootDir ?? process.cwd(), filePath)).sort(),
   };
 }
@@ -160,11 +166,13 @@ export function inspectSourceText(text, filePath = "source.js") {
     filePath,
     "specifier",
   );
+  const sdkDeprecations = inspectSdkDeprecations(searchableText, filePath);
 
   return {
     hooks,
     registrations,
     sdkImports,
+    sdkDeprecations,
   };
 }
 
@@ -353,6 +361,7 @@ function emptyInspection(fixture, status) {
     packageErrors: [],
     packageEntrypoints: [],
     sdkImports: [],
+    sdkDeprecations: [],
     sourceFiles: [],
   };
 }
@@ -554,3 +563,11 @@ function uniqueDetails(details) {
   }
   return [...byKey.values()];
 }
+
+function uniqueSdkDeprecations(details) {
+  const byKey = new Map();
+  for (const detail of [...details].sort((left, right) => left.ref.localeCompare(right.ref))) {
+    byKey.set(`${detail.code}:${detail.surface}:${detail.ref}`, detail);
+  }
+  return [...byKey.values()];
+}

package/src/issues.js

@@ -41,10 +41,17 @@ export const knownIssueCodes = new Set([
   "runtime-tool-capture",
   "reserved-sdk-import",
   "security-manifest-schema-unavailable",
+  "sdk-load-session-store",
   "sdk-export-missing",
   "unrecognized-security-manifest",
 ]);
 
+const authorRemediationDocsUrl = (code) => `https://docs.openclaw.ai/clawhub/plugin-validation-fixes#${code}`;
+
+const authorRemediation = (summary) => ({ summary });
+
+const migrationRemediation = authorRemediation;
+
 export const issueMetadataByCode = {
   "before-tool-call-probe": {
     severity: "P1",
@@ -63,6 +70,13 @@ export const issueMetadataByCode = {
     owner: "core",
     decision: "core-compat-adapter",
     title: "channelEnvVars legacy manifest metadata must stay covered",
+    authorRemediation: migrationRemediation(
+      "Move legacy channel environment variable metadata into the current setup/config metadata while keeping the old field until your supported OpenClaw range no longer needs it.",
+      [
+        "Mirror each channel environment variable into the current setup or provider configuration metadata.",
+        "Keep channelEnvVars only as backwards compatibility for older OpenClaw versions you still support.",
+      ],
+    ),
   },
   "conversation-access-hook": {
     severity: "P1",
@@ -75,12 +89,40 @@ export const issueMetadataByCode = {
     owner: "core",
     decision: "core-compat-adapter",
     title: "legacy before_agent_start hook compatibility is still used",
+    authorRemediation: migrationRemediation(
+      "Replace the legacy before_agent_start hook with the current prompt/model hooks.",
+      [
+        "Move model-selection work to before_model_resolve when possible.",
+        "Move prompt mutation work to before_prompt_build.",
+        "Keep before_agent_start only if your declared compatibility range still includes OpenClaw versions that require it.",
+      ],
+    ),
   },
   "legacy-root-sdk-import": {
     severity: "P2",
     owner: "core",
     decision: "core-compat-adapter",
     title: "root plugin SDK barrel is still used by fixtures",
+    authorRemediation: migrationRemediation(
+      "Prefer focused public plugin SDK subpath imports instead of the legacy root barrel.",
+      [
+        "Replace imports from openclaw/plugin-sdk with the documented subpath for the API you use.",
+        "Keep the root import only while supporting older OpenClaw versions that do not expose the subpath.",
+      ],
+    ),
+  },
+  "sdk-load-session-store": {
+    severity: "P2",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "deprecated whole-store session helper is still used",
+    authorRemediation: migrationRemediation(
+      "Replace deprecated loadSessionStore whole-store access with row-scoped session helpers.",
+      [
+        "Use getSessionEntry(...) or listSessionEntries(...) for reads instead of cloning the whole session store.",
+        "Use patchSessionEntry(...) or upsertSessionEntry(...) for writes instead of mutating and saving a whole-store object.",
+      ],
+    ),
   },
   "sdk-export-missing": {
     severity: "P1",
@@ -93,12 +135,26 @@ export const issueMetadataByCode = {
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "plugin imports reserved bundled-plugin SDK compatibility subpaths",
+    authorRemediation: authorRemediation(
+      "Stop importing reserved bundled-plugin SDK compatibility paths.",
+      [
+        "Replace reserved OpenClaw internal SDK imports with documented public openclaw/plugin-sdk subpaths.",
+        "If no public API exists for the behavior, vendor a plugin-local helper or request a public OpenClaw API.",
+      ],
+    ),
   },
   "security-manifest-schema-unavailable": {
     severity: "P3",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "plugin security manifest references an unavailable schema",
+    authorRemediation: authorRemediation(
+      "Remove or update the unsupported security manifest schema reference.",
+      [
+        "Delete the schema URL from openclaw.security.json if it is advisory-only.",
+        "Use a documented versioned schema once OpenClaw publishes one.",
+      ],
+    ),
   },
   "missing-compat-record": {
     severity: "P1",
@@ -117,18 +173,37 @@ export const issueMetadataByCode = {
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "manifest display name is missing",
+    authorRemediation: authorRemediation(
+      "Add a display name to the plugin manifest.",
+      ["Set a non-empty name field in openclaw.plugin.json."],
+      '{\n  "name": "My Plugin"\n}',
+    ),
   },
   "manifest-unknown-contracts": {
     severity: "P1",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "manifest declares unsupported contract keys",
+    authorRemediation: authorRemediation(
+      "Remove unsupported manifest contract keys or move them to a documented OpenClaw contract field.",
+      [
+        "Compare the contracts object to the OpenClaw manifest fields supported by your target version.",
+        "Delete custom contract keys unless OpenClaw has a versioned schema for them.",
+      ],
+    ),
   },
   "manifest-unknown-fields": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "manifest uses unsupported top-level fields",
+    authorRemediation: authorRemediation(
+      "Move unsupported top-level manifest fields into supported package metadata or remove them.",
+      [
+        "Keep openclaw.plugin.json limited to fields supported by the target OpenClaw manifest schema.",
+        "Move package-level metadata into package.json openclaw metadata when that field is supported.",
+      ],
+    ),
   },
   "package-build-artifact-entrypoint": {
     severity: "P2",
@@ -147,72 +222,159 @@ export const issueMetadataByCode = {
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package entrypoint is missing",
+    authorRemediation: authorRemediation(
+      "Publish the entrypoint declared in OpenClaw package metadata or update the metadata to point at an existing file.",
+      [
+        "Check package.json openclaw.extensions and openclaw.runtimeExtensions.",
+        "Ensure the referenced file exists in the published artifact, usually under dist/ after build.",
+      ],
+    ),
   },
   "package-install-metadata-incomplete": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package install metadata is incomplete",
+    authorRemediation: authorRemediation(
+      "Complete the OpenClaw install metadata so ClawHub can identify the install target.",
+      [
+        "Fill package.json openclaw.install with the supported release target.",
+        "Align clawhubSpec, npmSpec, and defaultChoice with the package you publish.",
+      ],
+    ),
   },
   "package-json-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "package metadata is missing",
+    authorRemediation: authorRemediation(
+      "Add a package.json to the plugin package.",
+      [
+        "Include the package name and version.",
+        "Add an openclaw metadata block describing extensions, compatibility, and install details.",
+      ],
+    ),
   },
   "package-manifest-version-drift": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "package and manifest versions drift",
+    authorRemediation: authorRemediation(
+      "Align the plugin version declared in package.json and openclaw.plugin.json.",
+      [
+        "Use the same version in both files, or remove stale manifest version metadata if package.json is authoritative.",
+        "Republish with a new package version after changing published metadata.",
+      ],
+    ),
   },
   "package-min-host-version-drift": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package minimum host version drifts from build target",
+    authorRemediation: authorRemediation(
+      "Set the package minimum host version to the OpenClaw version range the plugin was built and tested against.",
+      [
+        "Update package.json openclaw.install.minHostVersion or compatibility metadata.",
+        "Keep it semver-compatible with the target OpenClaw build version.",
+      ],
+    ),
   },
   "package-npm-pack-entrypoint-missing": {
     severity: "P1",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "advertised npm artifact is missing OpenClaw entrypoints",
+    authorRemediation: authorRemediation(
+      "Include the declared OpenClaw entrypoints in the npm-packed artifact.",
+      [
+        "Run npm pack locally and inspect the tarball contents.",
+        "Update package.json files so dist files and manifests are included.",
+        "Build before packing if the entrypoint is generated.",
+      ],
+    ),
   },
   "package-npm-pack-metadata-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "advertised npm artifact is missing OpenClaw metadata",
+    authorRemediation: authorRemediation(
+      "Include OpenClaw metadata files in the npm-packed artifact.",
+      [
+        "Run npm pack locally and inspect package.json and OpenClaw manifest files.",
+        "Update package.json files so required metadata is not excluded.",
+      ],
+    ),
   },
   "package-npm-pack-unavailable": {
     severity: "P1",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "advertised npm artifact cannot be packed",
+    authorRemediation: authorRemediation(
+      "Make the package packable before publishing it through ClawHub.",
+      [
+        "Remove private:true if this package is intended to publish.",
+        "Ensure package.json has a valid name and version.",
+        "Fix package scripts or files entries that make npm pack fail.",
+      ],
+    ),
   },
   "package-openclaw-entry-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package entrypoint metadata is missing",
+    authorRemediation: authorRemediation(
+      "Declare the plugin runtime entrypoint in package.json OpenClaw metadata.",
+      [
+        "Add openclaw.extensions for extension entrypoints.",
+        "Add openclaw.runtimeExtensions when the plugin has runtime-side code.",
+      ],
+    ),
   },
   "package-openclaw-metadata-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package metadata is missing",
+    authorRemediation: authorRemediation(
+      "Add the package.json openclaw metadata block.",
+      [
+        "Describe extension entrypoints, plugin API compatibility, and install metadata.",
+        "Keep package metadata in sync with openclaw.plugin.json when both files are present.",
+      ],
+    ),
   },
   "package-openclaw-unsupported-metadata": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "package declares unsupported OpenClaw metadata",
+    authorRemediation: authorRemediation(
+      "Remove unsupported OpenClaw package metadata fields.",
+      [
+        "Delete openclaw.bundle and other fields not accepted by the current package schema.",
+        "Move bundle-specific data to documented manifest fields when available.",
+      ],
+    ),
   },
   "package-plugin-api-compat-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "plugin API compatibility range is missing",
+    authorRemediation: authorRemediation(
+      "Declare the OpenClaw plugin API range this package supports.",
+      [
+        "Add package.json `openclaw.compat.pluginApi` with the OpenClaw plugin API range you tested.",
+        "If known, include the OpenClaw build/version used to produce the package metadata.",
+      ],
+      '"openclaw": {\n  "compat": {\n    "pluginApi": ">=0.1.0"\n  }\n}',
+    ),
   },
   "package-typescript-source-entrypoint": {
     severity: "P2",
@@ -225,6 +387,13 @@ export const issueMetadataByCode = {
     owner: "core",
     decision: "core-compat-adapter",
     title: "providerAuthEnvVars legacy manifest metadata must stay covered",
+    authorRemediation: migrationRemediation(
+      "Move legacy provider authentication environment variables into current provider setup metadata.",
+      [
+        "Mirror providerAuthEnvVars into setup.providers[].envVars or the current provider-choice metadata.",
+        "Keep the legacy field only while supporting older OpenClaw versions that still read it.",
+      ],
+    ),
   },
   "registration-capture-gap": {
     severity: "P2",
@@ -255,6 +424,13 @@ export const issueMetadataByCode = {
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "plugin ships an unsupported security manifest",
+    authorRemediation: authorRemediation(
+      "Remove unsupported security manifest files until OpenClaw documents a versioned security manifest schema.",
+      [
+        "Delete openclaw.security.json if it is advisory-only and not consumed by OpenClaw.",
+        "Reintroduce it only when the schema and ClawHub behavior are documented.",
+      ],
+    ),
   },
 };
 
@@ -284,6 +460,14 @@ export function buildIssues({ breakages = [], warnings = [], suggestions = [], t
       evidence: finding.evidence ?? [],
       compatRecord: finding.compatRecord ?? null,
       runtimeCoverage: finding.runtimeCoverage ?? null,
+      ...(finding.authorRemediation
+        ? {
+            authorRemediation: {
+              summary: finding.authorRemediation.summary,
+              docsUrl: authorRemediationDocsUrl(finding.code),
+            },
+          }
+        : {}),
     }));
 }
 
@@ -305,9 +489,18 @@ export function issueMetadata(finding, targetOpenClaw) {
     decision: "inspector-follow-up",
     title: finding.message,
   };
+  const authorMetadata = metadata.authorRemediation
+    ? {
+        authorRemediation: {
+          summary: metadata.authorRemediation.summary,
+          docsUrl: authorRemediationDocsUrl(finding.code),
+        },
+      }
+    : {};
   return {
     ...finding,
     ...metadata,
+    ...authorMetadata,
     ...classifyIssueFinding(finding, targetOpenClaw, metadata),
   };
 }
@@ -337,6 +530,10 @@ export function isInspectorGapFinding(finding, targetOpenClaw) {
   return issueMetadata(finding, targetOpenClaw).issueClass === "inspector-gap";
 }
 
+export function isAuthorFacingFinding(finding, targetOpenClaw) {
+  return Boolean(issueMetadata(finding, targetOpenClaw).authorRemediation);
+}
+
 export function summarizeIssueClasses(issues) {
   const summary = {
     "compat-gap": 0,
@@ -362,7 +559,16 @@ function issueClassFor(code, options) {
   if (code === "missing-compat-record") {
     return "compat-gap";
   }
-  if (options.deprecated || ["channel-env-vars", "legacy-before-agent-start", "legacy-root-sdk-import", "provider-auth-env-vars"].includes(code)) {
+  if (
+    options.deprecated ||
+    [
+      "channel-env-vars",
+      "legacy-before-agent-start",
+      "legacy-root-sdk-import",
+      "provider-auth-env-vars",
+      "sdk-load-session-store",
+    ].includes(code)
+  ) {
     return "deprecation-warning";
   }
   if (

package/src/report.js

@@ -3,7 +3,7 @@ import { renderMarkdownTable, writeArtifacts, writeJsonMarkdownArtifacts } from
 import { renderCompatibilityIssuesReport, renderCompatibilityMarkdownReport } from "./compatibility-report.js";
 import { buildContractProbes } from "./contract-probes.js";
 import { classifyCompatibilityFixture } from "./fixture-summary.js";
-import { buildIssues, isInspectorGapFinding, summarizeIssueClasses } from "./issues.js";
+import { buildIssues, isAuthorFacingFinding, summarizeIssueClasses } from "./issues.js";
 import { sanitizeReportArtifact } from "./report-sanitizer.js";
 import { applyRuntimeExecutionCoverage } from "./runtime-reconciliation.js";
 
@@ -26,6 +26,7 @@ export function buildReport({ config, inspections, failures = [], generatedAt =
       registrations: inspection.registrations,
       manifestContracts: inspection.manifestContracts,
       sdkImports: inspection.sdkImports,
+      sdkDeprecations: inspection.sdkDeprecations,
       sourceFiles: inspection.sourceFiles,
       manifestFiles: inspection.manifestFiles,
       packageFiles: inspection.packageFiles,
@@ -141,14 +142,16 @@ export async function buildCompatibilityReport(options = {}) {
     decisions,
   });
 
+  const visibleBreakages = filterVisibleFindings(breakages, targetOpenClaw, options);
   const visibleWarnings = filterVisibleFindings(warnings, targetOpenClaw, options);
   const visibleSuggestions = filterVisibleFindings(suggestions, targetOpenClaw, options);
+  const visibleDecisions = options.authorFacing === true ? [] : decisions;
   const runtimeCoverage = applyRuntimeExecutionCoverage({
     findings: [...visibleWarnings, ...visibleSuggestions],
     executionResults: options.executionResults,
   });
   const issues = buildIssues({
-    breakages,
+    breakages: visibleBreakages,
     warnings: visibleWarnings,
     suggestions: visibleSuggestions,
     targetOpenClaw,
@@ -166,14 +169,14 @@ export async function buildCompatibilityReport(options = {}) {
   return {
     generatedAt: options.generatedAt ?? "deterministic",
     targetOpenClaw,
-    status: breakages.length === 0 ? "pass" : "fail",
+    status: visibleBreakages.length === 0 ? "pass" : "fail",
     summary: {
       fixtureCount: fixtureReports.length,
       highPriorityFixtures: fixtureReports.filter((fixture) => fixture.priority === "high").length,
-      breakageCount: breakages.length,
+      breakageCount: visibleBreakages.length,
       warningCount: visibleWarnings.length,
       suggestionCount: visibleSuggestions.length,
-      decisionCount: decisions.length,
+      decisionCount: visibleDecisions.length,
       logCount: logs.length,
       issueCount: issues.length,
       openIssueCount: openIssues.length,
@@ -195,21 +198,21 @@ export async function buildCompatibilityReport(options = {}) {
       contractProbeCount: contractProbes.length,
     },
     fixtures: fixtureReports,
-    breakages,
+    breakages: visibleBreakages,
     warnings: visibleWarnings,
     suggestions: visibleSuggestions,
     issues,
     contractProbes,
     logs,
-    decisions,
+    decisions: visibleDecisions,
   };
 }
 
 function filterVisibleFindings(findings, targetOpenClaw, options) {
-  if (options.includeInspectorGaps === true) {
+  if (options.authorFacing !== true) {
     return findings;
   }
-  return findings.filter((finding) => !isInspectorGapFinding(finding, targetOpenClaw));
+  return findings.filter((finding) => isAuthorFacingFinding(finding, targetOpenClaw));
 }
 
 export function classifyCompatRecordCoverage({ targetOpenClaw, findings, suggestions, logs, decisions }) {
@@ -475,6 +478,7 @@ function defaultCompatibilityFixtureReport({ fixture, inspection }) {
     packages: [],
     sdkImports: inspection.sdkImports.map((sdkImport) => sdkImport.specifier).filter(Boolean),
     sdkImportDetails: inspection.sdkImports,
+    sdkDeprecations: inspection.sdkDeprecations,
   };
 }
 
@@ -493,6 +497,7 @@ function normalizeInspection(inspection, fixture) {
     packageErrors: [],
     packageEntrypoints: [],
     sdkImports: [],
+    sdkDeprecations: [],
     sourceFiles: [],
     ...inspection,
   };

package/src/sdk-deprecation-rules.js

@@ -0,0 +1,369 @@
+const loadSessionStoreReplacement =
+  "getSessionEntry(...) / listSessionEntries(...) for reads and patchSessionEntry(...) / upsertSessionEntry(...) for writes";
+
+const loadSessionStoreSpecifiers = new Set([
+  "openclaw/plugin-sdk/config-runtime",
+  "openclaw/plugin-sdk/session-store-runtime",
+]);
+
+export const pluginSdkDeprecationRules = [
+  {
+    code: "sdk-load-session-store",
+    title: "deprecated whole-store session helper is still used",
+    replacement: loadSessionStoreReplacement,
+  },
+];
+
+export function inspectSdkDeprecations(text, filePath = "source.js", rules = pluginSdkDeprecationRules) {
+  const findings = [];
+
+  for (const rule of rules) {
+    if (rule.code === "sdk-load-session-store") {
+      collectLoadSessionStoreDeprecations(findings, { text, filePath, rule });
+    }
+  }
+
+  return uniqueFindings(findings)
+    .sort((left, right) => left.offset - right.offset || left.surface.localeCompare(right.surface))
+    .map(({ offset, ...finding }) => finding);
+}
+
+function collectLoadSessionStoreDeprecations(findings, context) {
+  collectNamedImportDeprecations(findings, context);
+  collectNamedReexportDeprecations(findings, context);
+  collectNamedRequireDeprecations(findings, context);
+  collectNamespaceUsageDeprecations(findings, context);
+  collectNamespaceRequireDeprecations(findings, context);
+  collectRuntimeUsageDeprecations(findings, context);
+}
+
+function collectNamedImportDeprecations(findings, context) {
+  const regex =
+    /\bimport\s+(?:type\s+)?(?:[A-Za-z_$][\w$]*\s*,\s*)?{([^}]+)}\s*from\s*["'`]([^"'`]+)["'`]/g;
+  for (const match of context.text.matchAll(regex)) {
+    const specifier = match[2];
+    if (!loadSessionStoreSpecifiers.has(specifier)) {
+      continue;
+    }
+    for (const binding of parseNamedBindings(match[1])) {
+      if (binding.exported !== "loadSessionStore") {
+        continue;
+      }
+      findings.push(
+        buildFinding(context.rule, {
+          surface: `${specifier} import`,
+          sourceText: context.text,
+          filePath: context.filePath,
+          offset: (match.index ?? 0) + match[0].lastIndexOf(binding.local),
+        }),
+      );
+    }
+  }
+}
+
+function collectNamedReexportDeprecations(findings, context) {
+  const regex = /\bexport\s*{([^}]+)}\s*from\s*["'`]([^"'`]+)["'`]/g;
+  for (const match of context.text.matchAll(regex)) {
+    const specifier = match[2];
+    if (!loadSessionStoreSpecifiers.has(specifier)) {
+      continue;
+    }
+    for (const binding of parseNamedBindings(match[1])) {
+      if (binding.exported !== "loadSessionStore") {
+        continue;
+      }
+      findings.push(
+        buildFinding(context.rule, {
+          surface: `${specifier} re-export`,
+          sourceText: context.text,
+          filePath: context.filePath,
+          offset: (match.index ?? 0) + match[0].lastIndexOf(binding.local),
+        }),
+      );
+    }
+  }
+}
+
+function collectNamedRequireDeprecations(findings, context) {
+  const regex = /\b(?:const|let|var)\s+{([^}]+)}\s*=\s*require\(\s*["'`]([^"'`]+)["'`]\s*\)/g;
+  for (const match of context.text.matchAll(regex)) {
+    const specifier = match[2];
+    if (!loadSessionStoreSpecifiers.has(specifier)) {
+      continue;
+    }
+    for (const binding of parseNamedBindings(match[1], { aliasSeparator: ":" })) {
+      if (binding.exported !== "loadSessionStore") {
+        continue;
+      }
+      findings.push(
+        buildFinding(context.rule, {
+          surface: `${specifier} require`,
+          sourceText: context.text,
+          filePath: context.filePath,
+          offset: (match.index ?? 0) + match[0].lastIndexOf(binding.local),
+        }),
+      );
+    }
+  }
+}
+
+function collectMemberCallDeprecations(findings, context, options) {
+  forEachMethodCall(context.text, "loadSessionStore", (offset) => {
+    // Normalize transparent parentheses and optional-chained member links before matching.
+    const receiver = readNormalizedCallReceiver(context.text, offset);
+    if (!receiver || !options.receiverMatcher(receiver)) {
+      return;
+    }
+    findings.push(
+      buildFinding(context.rule, {
+        surface: options.surface,
+        sourceText: context.text,
+        filePath: context.filePath,
+        offset,
+      }),
+    );
+  });
+}
+
+function forEachMethodCall(text, methodName, visit) {
+  let start = 0;
+  while (start < text.length) {
+    const offset = text.indexOf(methodName, start);
+    if (offset === -1) {
+      return;
+    }
+    start = offset + methodName.length;
+    if (!isIdentifierBoundary(text, offset - 1) || !isIdentifierBoundary(text, offset + methodName.length)) {
+      continue;
+    }
+    if (!hasCallSuffix(text, offset + methodName.length)) {
+      continue;
+    }
+    visit(offset);
+  }
+}
+
+function readNormalizedCallReceiver(text, methodOffset) {
+  let cursor = skipWhitespaceBackward(text, methodOffset);
+  const operator = readMemberAccessOperator(text, cursor);
+  if (!operator) {
+    return null;
+  }
+  cursor = operator.start;
+  const receiverStart = findReceiverStart(text, cursor);
+  if (receiverStart === cursor) {
+    return null;
+  }
+  return normalizeReceiverExpression(text.slice(receiverStart, cursor));
+}
+
+function readMemberAccessOperator(text, endOffset) {
+  if (endOffset >= 2 && text.slice(endOffset - 2, endOffset) === "?.") {
+    return { kind: "optional", start: endOffset - 2 };
+  }
+  if (endOffset >= 1 && text[endOffset - 1] === ".") {
+    return { kind: "direct", start: endOffset - 1 };
+  }
+  return null;
+}
+
+function findReceiverStart(text, endOffset) {
+  let cursor = endOffset;
+  let parenDepth = 0;
+  while (cursor > 0) {
+    const char = text[cursor - 1];
+    if (char === ")") {
+      parenDepth += 1;
+      cursor -= 1;
+      continue;
+    }
+    if (char === "(") {
+      if (parenDepth === 0) {
+        break;
+      }
+      parenDepth -= 1;
+      cursor -= 1;
+      continue;
+    }
+    if (parenDepth > 0) {
+      cursor -= 1;
+      continue;
+    }
+    if (isReceiverCharacter(char)) {
+      cursor -= 1;
+      continue;
+    }
+    break;
+  }
+  return cursor;
+}
+
+function normalizeReceiverExpression(rawReceiver) {
+  let normalized = rawReceiver.replace(/\s+/g, "");
+  while (normalized.startsWith("(") && normalized.endsWith(")") && wrapsWholeExpression(normalized)) {
+    normalized = normalized.slice(1, -1);
+  }
+  return normalized.replaceAll("?.", ".");
+}
+
+function wrapsWholeExpression(value) {
+  let depth = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (char === "(") {
+      depth += 1;
+    } else if (char === ")") {
+      depth -= 1;
+      if (depth === 0 && index < value.length - 1) {
+        return false;
+      }
+    }
+  }
+  return depth === 0;
+}
+
+function hasCallSuffix(text, startOffset) {
+  let cursor = skipWhitespaceForward(text, startOffset);
+  if (text.slice(cursor, cursor + 2) === "?.") {
+    cursor = skipWhitespaceForward(text, cursor + 2);
+  }
+  return text[cursor] === "(";
+}
+
+function skipWhitespaceForward(text, startOffset) {
+  let cursor = startOffset;
+  while (cursor < text.length && /\s/.test(text[cursor])) {
+    cursor += 1;
+  }
+  return cursor;
+}
+
+function skipWhitespaceBackward(text, endOffset) {
+  let cursor = endOffset;
+  while (cursor > 0 && /\s/.test(text[cursor - 1])) {
+    cursor -= 1;
+  }
+  return cursor;
+}
+
+function isReceiverCharacter(char) {
+  return /[A-Za-z0-9_$?.]/.test(char);
+}
+
+function isIdentifierBoundary(text, offset) {
+  if (offset < 0 || offset >= text.length) {
+    return true;
+  }
+  return !/[A-Za-z0-9_$]/.test(text[offset]);
+}
+
+function isRuntimeSessionReceiver(receiver) {
+  return /^(?:[A-Za-z_$][A-Za-z0-9_$]*|this)\.runtime\.agent\.session$/.test(receiver);
+}
+
+function collectNamespaceUsageDeprecations(findings, context) {
+  const regex = /\bimport\s+(?:type\s+)?\*\s+as\s+([A-Za-z_$][\w$]*)\s*from\s*["'`]([^"'`]+)["'`]/g;
+  for (const match of context.text.matchAll(regex)) {
+    const local = match[1];
+    const specifier = match[2];
+    if (!loadSessionStoreSpecifiers.has(specifier)) {
+      continue;
+    }
+    collectMemberCallDeprecations(findings, context, {
+      receiverMatcher: (receiver) => receiver === local,
+      surface: `${specifier} namespace access`,
+    });
+  }
+}
+
+function collectNamespaceRequireDeprecations(findings, context) {
+  const regex = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*require\(\s*["'`]([^"'`]+)["'`]\s*\)/g;
+  for (const match of context.text.matchAll(regex)) {
+    const local = match[1];
+    const specifier = match[2];
+    if (!loadSessionStoreSpecifiers.has(specifier)) {
+      continue;
+    }
+    collectMemberCallDeprecations(findings, context, {
+      receiverMatcher: (receiver) => receiver === local,
+      surface: `${specifier} require namespace access`,
+    });
+  }
+}
+
+function collectRuntimeUsageDeprecations(findings, context) {
+  collectMemberCallDeprecations(findings, context, {
+    receiverMatcher: isRuntimeSessionReceiver,
+    surface: "api.runtime.agent.session",
+  });
+}
+
+function parseNamedBindings(rawBindings, options = {}) {
+  const aliasSeparator = options.aliasSeparator ?? "as";
+  return rawBindings
+    .split(",")
+    .map((binding) => binding.trim())
+    .filter(Boolean)
+    .map((binding) => binding.replace(/^type\s+/, "").trim())
+    .map((binding) => parseBindingAlias(binding, aliasSeparator))
+    .filter((binding) => binding.exported && binding.local);
+}
+
+function parseBindingAlias(binding, aliasSeparator) {
+  if (aliasSeparator === ":") {
+    const separatorIndex = binding.indexOf(":");
+    if (separatorIndex === -1) {
+      return {
+        exported: binding.trim(),
+        local: binding.trim(),
+      };
+    }
+    return {
+      exported: binding.slice(0, separatorIndex).trim(),
+      local: binding.slice(separatorIndex + 1).trim(),
+    };
+  }
+
+  const tokens = binding.trim().split(/\s+/);
+  if (tokens.length === 3 && tokens[1] === "as") {
+    return {
+      exported: tokens[0],
+      local: tokens[2],
+    };
+  }
+
+  return {
+    exported: binding.trim(),
+    local: binding.trim(),
+  };
+}
+
+function buildFinding(rule, details) {
+  const refLine = lineForOffset(details.sourceText, details.offset);
+  return {
+    code: rule.code,
+    surface: details.surface,
+    replacement: rule.replacement,
+    ref: `${details.filePath}:${refLine}`,
+    message: `loadSessionStore keeps the legacy whole-store session shape; use ${rule.replacement}.`,
+    offset: details.offset,
+  };
+}
+
+function uniqueFindings(findings) {
+  const byKey = new Map();
+  for (const finding of findings) {
+    byKey.set(`${finding.code}:${finding.surface}:${finding.ref}`, finding);
+  }
+  return [...byKey.values()];
+}
+
+function lineForOffset(text, offset) {
+  let line = 1;
+  for (let index = 0; index < offset; index += 1) {
+    if (text.charCodeAt(index) === 10) {
+      line += 1;
+    }
+  }
+  return line;
+}