docs: document channel plugin contracts

src/channels/plugins/actions/reaction-message-id.test.ts

@@ -1,3 +1,4 @@
+// Reaction message id tests cover channel action message id extraction and normalization.
 import { describe, expect, it } from "vitest";
 import { resolveReactionMessageId } from "./reaction-message-id.js";
 

src/channels/plugins/contracts/channel-catalog.contract.test.ts

@@ -1,3 +1,4 @@
+// Channel catalog contract tests cover bundled and registry-backed channel catalog invariants.
 import {
   describeBundledMetadataOnlyChannelCatalogContract,
   describeChannelCatalogEntryContract,

src/channels/plugins/contracts/channel-import-guardrails.test.ts

@@ -1,3 +1,4 @@
+// Channel import guardrail tests cover forbidden imports across channel plugin boundaries.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import { basename, dirname, resolve } from "node:path";

src/channels/plugins/contracts/directory.registry-backed-shard-a.contract.test.ts

@@ -1,3 +1,4 @@
+// Directory registry shard A tests cover directory channel contracts against registry-backed fixtures.
 import { installDirectoryContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installDirectoryContractRegistryShard({ shardIndex: 0, shardCount: 8 });

src/channels/plugins/contracts/directory.registry-backed-shard-b.contract.test.ts

@@ -1,3 +1,4 @@
+// Directory registry shard B tests cover directory channel contracts against registry-backed fixtures.
 import { installDirectoryContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installDirectoryContractRegistryShard({ shardIndex: 1, shardCount: 8 });

src/channels/plugins/contracts/directory.registry-backed-shard-c.contract.test.ts

@@ -1,3 +1,4 @@
+// Directory registry shard C tests cover directory channel contracts against registry-backed fixtures.
 import { installDirectoryContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installDirectoryContractRegistryShard({ shardIndex: 2, shardCount: 8 });

src/channels/plugins/contracts/directory.registry-backed-shard-d.contract.test.ts

@@ -1,3 +1,4 @@
+// Directory registry shard D tests cover directory channel contracts against registry-backed fixtures.
 import { installDirectoryContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installDirectoryContractRegistryShard({ shardIndex: 3, shardCount: 8 });

src/channels/plugins/contracts/directory.registry-backed-shard-e.contract.test.ts

@@ -1,3 +1,4 @@
+// Directory registry shard E tests cover directory channel contracts against registry-backed fixtures.
 import { installDirectoryContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installDirectoryContractRegistryShard({ shardIndex: 4, shardCount: 8 });

src/channels/plugins/contracts/directory.registry-backed-shard-f.contract.test.ts

@@ -1,3 +1,4 @@
+// Directory registry shard F tests cover directory channel contracts against registry-backed fixtures.
 import { installDirectoryContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installDirectoryContractRegistryShard({ shardIndex: 5, shardCount: 8 });

src/channels/plugins/contracts/directory.registry-backed-shard-g.contract.test.ts

@@ -1,3 +1,4 @@
+// Directory registry shard G tests cover directory channel contracts against registry-backed fixtures.
 import { installDirectoryContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installDirectoryContractRegistryShard({ shardIndex: 6, shardCount: 8 });

src/channels/plugins/contracts/directory.registry-backed-shard-h.contract.test.ts

@@ -1,3 +1,4 @@
+// Directory registry shard H tests cover directory channel contracts against registry-backed fixtures.
 import { installDirectoryContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installDirectoryContractRegistryShard({ shardIndex: 7, shardCount: 8 });

src/channels/plugins/contracts/group-policy.fallback.contract.test.ts

@@ -1,3 +1,4 @@
+// Group policy fallback contract tests cover default group policy behavior for channel plugins.
 import { describe, expect, it } from "vitest";
 import { resolveOpenProviderRuntimeGroupPolicy } from "../../../config/runtime-group-policy.js";
 import { installChannelRuntimeGroupPolicyFallbackSuite } from "./test-helpers/group-policy-contract-suites.js";

src/channels/plugins/contracts/outbound-payload.contract.test.ts

@@ -1,3 +1,4 @@
+// Outbound payload contract tests cover channel plugin outbound payload shape and normalization.
 import { describe, vi } from "vitest";
 import { createDirectTextMediaOutbound } from "../outbound/direct-text-media.js";
 import {

src/channels/plugins/contracts/plugin.registry-backed-shard-a.contract.test.ts

@@ -1,3 +1,4 @@
+// Plugin registry shard A tests cover channel plugin contracts against registry-backed fixtures.
 import { installPluginContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installPluginContractRegistryShard({ shardIndex: 0, shardCount: 8 });

src/channels/plugins/contracts/plugin.registry-backed-shard-b.contract.test.ts

@@ -1,3 +1,4 @@
+// Plugin registry shard B tests cover channel plugin contracts against registry-backed fixtures.
 import { installPluginContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installPluginContractRegistryShard({ shardIndex: 1, shardCount: 8 });

src/channels/plugins/contracts/plugin.registry-backed-shard-c.contract.test.ts

@@ -1,3 +1,4 @@
+// Plugin registry shard C tests cover channel plugin contracts against registry-backed fixtures.
 import { installPluginContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installPluginContractRegistryShard({ shardIndex: 2, shardCount: 8 });

src/channels/plugins/contracts/plugin.registry-backed-shard-d.contract.test.ts

@@ -1,3 +1,4 @@
+// Plugin registry shard D tests cover channel plugin contracts against registry-backed fixtures.
 import { installPluginContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installPluginContractRegistryShard({ shardIndex: 3, shardCount: 8 });

src/channels/plugins/contracts/plugin.registry-backed-shard-e.contract.test.ts

@@ -1,3 +1,4 @@
+// Plugin registry shard E tests cover channel plugin contracts against registry-backed fixtures.
 import { installPluginContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installPluginContractRegistryShard({ shardIndex: 4, shardCount: 8 });

src/channels/plugins/contracts/plugin.registry-backed-shard-f.contract.test.ts

@@ -1,3 +1,4 @@
+// Plugin registry shard F tests cover channel plugin contracts against registry-backed fixtures.
 import { installPluginContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installPluginContractRegistryShard({ shardIndex: 5, shardCount: 8 });

src/channels/plugins/contracts/plugin.registry-backed-shard-g.contract.test.ts

@@ -1,3 +1,4 @@
+// Plugin registry shard G tests cover channel plugin contracts against registry-backed fixtures.
 import { installPluginContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installPluginContractRegistryShard({ shardIndex: 6, shardCount: 8 });

src/channels/plugins/contracts/plugin.registry-backed-shard-h.contract.test.ts

@@ -1,3 +1,4 @@
+// Plugin registry shard H tests cover channel plugin contracts against registry-backed fixtures.
 import { installPluginContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installPluginContractRegistryShard({ shardIndex: 7, shardCount: 8 });

src/channels/plugins/contracts/plugins-core.authorize-config-write.policy.contract.test.ts

@@ -1,3 +1,4 @@
+// Config write policy contract tests cover channel plugin authorization policy decisions.
 import { describeChannelConfigWritePolicyContract } from "./test-helpers/config-write-contract-suites.js";
 
 describeChannelConfigWritePolicyContract();

src/channels/plugins/contracts/plugins-core.authorize-config-write.targets.contract.test.ts

@@ -1,3 +1,4 @@
+// Config write target contract tests cover channel plugin target authorization rules.
 import { describeChannelConfigWriteTargetContract } from "./test-helpers/config-write-contract-suites.js";
 
 describeChannelConfigWriteTargetContract();

src/channels/plugins/contracts/plugins-core.catalog.entries.contract.test.ts

@@ -1,3 +1,4 @@
+// Catalog entry contract tests cover channel plugin catalog metadata and entry invariants.
 import { describeChannelPluginCatalogEntriesContract } from "./test-helpers/channel-plugin-catalog-contract-suites.js";
 
 describeChannelPluginCatalogEntriesContract();

src/channels/plugins/contracts/plugins-core.catalog.paths.contract.test.ts

@@ -1,3 +1,4 @@
+// Catalog path contract tests cover channel plugin package path and catalog resolution.
 import { describeChannelPluginCatalogPathResolutionContract } from "./test-helpers/channel-plugin-catalog-contract-suites.js";
 
 describeChannelPluginCatalogPathResolutionContract();

src/channels/plugins/contracts/plugins-core.loader.contract.test.ts

@@ -1,3 +1,4 @@
+// Plugins core loader contract tests cover channel plugin loader setup and teardown behavior.
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { setActivePluginRegistry } from "../../../plugins/runtime.js";
 import {

src/channels/plugins/contracts/plugins-core.registry.contract.test.ts

@@ -1,3 +1,4 @@
+// Plugins core registry contract tests cover channel plugin registry behavior and cleanup.
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { setActivePluginRegistry } from "../../../plugins/runtime.js";
 import { createTestRegistry } from "../../../test-utils/channel-plugins.js";

src/channels/plugins/contracts/plugins-core.resolve-config-writes.contract.test.ts

@@ -1,3 +1,4 @@
+// Config write resolution contract tests cover channel plugin config write normalization.
 import { describe, expect, it } from "vitest";
 import { resolveChannelConfigWrites } from "../config-writes.js";
 

src/channels/plugins/contracts/registry.contract.test.ts

@@ -1,3 +1,4 @@
+// Registry contract tests cover shared channel plugin registry contract behavior.
 import { describe, expect, it } from "vitest";
 import { sessionBindingContractChannelIds } from "./test-helpers/manifest.js";
 

src/channels/plugins/contracts/session-binding.registry-backed.contract.test.ts

@@ -1,3 +1,4 @@
+// Session binding registry contract tests cover channel session binding across registry fixtures.
 import { getSessionBindingContractRegistry } from "./test-helpers/registry-session-binding.js";
 import { describeSessionBindingRegistryBackedContract } from "./test-helpers/session-binding-registry-backed-contract.js";
 

src/channels/plugins/contracts/surfaces-only.registry-backed-shard-a.contract.test.ts

@@ -1,3 +1,4 @@
+// Surface registry shard A tests cover exposed channel plugin surfaces against registry fixtures.
 import { installSurfaceContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installSurfaceContractRegistryShard({ shardIndex: 0, shardCount: 8 });

src/channels/plugins/contracts/surfaces-only.registry-backed-shard-b.contract.test.ts

@@ -1,3 +1,4 @@
+// Surface registry shard B tests cover exposed channel plugin surfaces against registry fixtures.
 import { installSurfaceContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installSurfaceContractRegistryShard({ shardIndex: 1, shardCount: 8 });

src/channels/plugins/contracts/surfaces-only.registry-backed-shard-c.contract.test.ts

@@ -1,3 +1,4 @@
+// Surface registry shard C tests cover exposed channel plugin surfaces against registry fixtures.
 import { installSurfaceContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installSurfaceContractRegistryShard({ shardIndex: 2, shardCount: 8 });

src/channels/plugins/contracts/surfaces-only.registry-backed-shard-d.contract.test.ts

@@ -1,3 +1,4 @@
+// Surface registry shard D tests cover exposed channel plugin surfaces against registry fixtures.
 import { installSurfaceContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installSurfaceContractRegistryShard({ shardIndex: 3, shardCount: 8 });

src/channels/plugins/contracts/surfaces-only.registry-backed-shard-e.contract.test.ts

@@ -1,3 +1,4 @@
+// Surface registry shard E tests cover exposed channel plugin surfaces against registry fixtures.
 import { installSurfaceContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installSurfaceContractRegistryShard({ shardIndex: 4, shardCount: 8 });

src/channels/plugins/contracts/surfaces-only.registry-backed-shard-f.contract.test.ts

@@ -1,3 +1,4 @@
+// Surface registry shard F tests cover exposed channel plugin surfaces against registry fixtures.
 import { installSurfaceContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installSurfaceContractRegistryShard({ shardIndex: 5, shardCount: 8 });

src/channels/plugins/contracts/surfaces-only.registry-backed-shard-g.contract.test.ts

@@ -1,3 +1,4 @@
+// Surface registry shard G tests cover exposed channel plugin surfaces against registry fixtures.
 import { installSurfaceContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installSurfaceContractRegistryShard({ shardIndex: 6, shardCount: 8 });

src/channels/plugins/contracts/surfaces-only.registry-backed-shard-h.contract.test.ts

@@ -1,3 +1,4 @@
+// Surface registry shard H tests cover exposed channel plugin surfaces against registry fixtures.
 import { installSurfaceContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installSurfaceContractRegistryShard({ shardIndex: 7, shardCount: 8 });

src/channels/plugins/contracts/threading.registry-backed-shard-a.contract.test.ts

@@ -1,3 +1,4 @@
+// Threading registry shard A tests cover thread binding contracts against registry-backed fixtures.
 import { installThreadingContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installThreadingContractRegistryShard({ shardIndex: 0, shardCount: 8 });

src/channels/plugins/contracts/threading.registry-backed-shard-b.contract.test.ts

@@ -1,3 +1,4 @@
+// Threading registry shard B tests cover thread binding contracts against registry-backed fixtures.
 import { installThreadingContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installThreadingContractRegistryShard({ shardIndex: 1, shardCount: 8 });

src/channels/plugins/contracts/threading.registry-backed-shard-c.contract.test.ts

@@ -1,3 +1,4 @@
+// Threading registry shard C tests cover thread binding contracts against registry-backed fixtures.
 import { installThreadingContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installThreadingContractRegistryShard({ shardIndex: 2, shardCount: 8 });

src/channels/plugins/contracts/threading.registry-backed-shard-d.contract.test.ts

@@ -1,3 +1,4 @@
+// Threading registry shard D tests cover thread binding contracts against registry-backed fixtures.
 import { installThreadingContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installThreadingContractRegistryShard({ shardIndex: 3, shardCount: 8 });

src/channels/plugins/contracts/threading.registry-backed-shard-e.contract.test.ts

@@ -1,3 +1,4 @@
+// Threading registry shard E tests cover thread binding contracts against registry-backed fixtures.
 import { installThreadingContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installThreadingContractRegistryShard({ shardIndex: 4, shardCount: 8 });

src/channels/plugins/contracts/threading.registry-backed-shard-f.contract.test.ts

@@ -1,3 +1,4 @@
+// Threading registry shard F tests cover thread binding contracts against registry-backed fixtures.
 import { installThreadingContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installThreadingContractRegistryShard({ shardIndex: 5, shardCount: 8 });

src/channels/plugins/contracts/threading.registry-backed-shard-g.contract.test.ts

@@ -1,3 +1,4 @@
+// Threading registry shard G tests cover thread binding contracts against registry-backed fixtures.
 import { installThreadingContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installThreadingContractRegistryShard({ shardIndex: 6, shardCount: 8 });

src/channels/plugins/contracts/threading.registry-backed-shard-h.contract.test.ts

@@ -1,3 +1,4 @@
+// Threading registry shard H tests cover thread binding contracts against registry-backed fixtures.
 import { installThreadingContractRegistryShard } from "./test-helpers/registry-backed-contract-shards.js";
 
 installThreadingContractRegistryShard({ shardIndex: 7, shardCount: 8 });

src/channels/plugins/outbound/direct-text-media.test.ts

@@ -1,3 +1,4 @@
+// Direct text media outbound tests cover text and media delivery payload normalization.
 import { describe, expect, it, vi } from "vitest";
 import {
   sendPayloadMediaSequenceAndFinalize,

src/channels/plugins/outbound/interactive.test.ts

@@ -1,3 +1,4 @@
+// Interactive outbound tests cover channel outbound interactive payload construction.
 import { describe, expect, it } from "vitest";
 import {
   adaptMessagePresentationForChannel,