@deepseek-ai/dsh-experimental-forge 0.0.0-stage → 0.2.2-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,37 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/experimental/forge/README.md
+/:
+  en: 58d73ee11cb9ecde
+  zh: 04213727345a58a2
+/deepseek-ai-dsh-experimental-forge:
+  en: cf24b0ee1e2732e8
+  zh: bb4e76d2b69b84d8
+/deepseek-ai-dsh-experimental-forge/summary:
+  en: 2d79427980c092c3
+  zh: ee18048c6cc0aeec
+/deepseek-ai-dsh-experimental-forge/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 2f8a621b991260a1
+/deepseek-ai-dsh-experimental-forge/use-this-package:
+  en: 5f4f14ee9aad5072
+  zh: 6c8606796df24a3e
+/deepseek-ai-dsh-experimental-forge/understand-the-implementation:
+  en: e193cb547c47069b
+  zh: faa517522402ea41
+/deepseek-ai-dsh-experimental-forge/further-exploration:
+  en: bb13125144d413d5
+  zh: a6832dad7a093bfe
+/deepseek-ai-dsh-experimental-forge/model-experience:
+  en: a62b9af05181f74f
+  zh: 64b8b0aa18c64c57
+/deepseek-ai-dsh-experimental-forge/model-experience/kv-cache-effect:
+  en: 1675c9fcae96936c
+  zh: 5cd2a82aeca3160a
+/deepseek-ai-dsh-experimental-forge/known-limitations-and-deferred-work:
+  en: 0721de59f78c48e6
+  zh: 094ca6e3bba766ba
+/deepseek-ai-dsh-experimental-forge/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+---
+description: "Register code host providers and poll change request status through one provider-neutral service."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @deepseek-ai/dsh-experimental-forge
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Read and act on pull requests and merge requests without coupling consumers to one code host. A provider maps remote and change request URLs to provider-neutral references, finds change requests by head branch, reads their status in batches, reads their diffs and files, and marks drafts ready or merges on request. Watchers of one change request share a single polling loop whose cadence follows check, mergeability, and lifecycle state.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the registry with at least one provider package, such as the GitHub provider.
+
+```yaml
+- name: '@deepseek-ai/dsh-experimental-forge'
+- name: '@deepseek-ai/dsh-experimental-forge-github'
+```
+
+`ctx.forge.register(provider)` is an effect on the calling fiber and returns an async disposer that cancels and drains that registration's calls. Results arriving after cancellation are discarded. One provider serves one forge family; registering a second provider for the same family throws. Registration changes announce `forge/providers-changed`; registering a provider polls its existing watches immediately. `repositoryFromRemote(url)` and `changeRequestFromUrl(url)` ask providers in registration order and return the first match. `changeRequestUrl(ref)`, `findByHead(repository, branch, signal)`, and `readiness(repository, signal)` delegate to the provider of the reference's forge and throw when none is registered; `readiness` reports whether the provider can reach the host with current credentials.
+
+`markReady(ref, signal)` marks a draft ready for review, and `merge(ref, { method, headSha }, signal)` merges a change request only while its head is still `headSha`. Both delegate to the provider of the reference's forge, throw when none is registered, and resolve to undefined once the host accepted the change or to a `ForgeActionFailure`: `unauthenticated`, `stale` when the head moved past `headSha`, or `failed` with the host's reason. After either settles, a watched change request is polled at once. Snapshots carry `mergeReady`, whether the host would merge the change request now for the signed-in user, and `mergeMethods`, the methods the repository accepts with that user's usual one first.
+
+`diff(ref, signal)` reads the change request's unified patch as the host computes it, with `a/` and `b/` path prefixes, and `fileText(ref, commit, path, signal)` reads one file of its repository at a commit. Both delegate to the provider of the reference's forge, throw when none is registered, and resolve to the text or to a `ForgeFailure`, which is `too-large` when the host or the provider refuses an answer over its size limit. `fileUrl(ref, commit, path)` returns the web page of that file at that commit.
+
+`ctx.forge.watch(ref, listener)` is also an effect. The first watcher of a change request polls it at once; `latest(ref)` returns the most recent result. Each forge has at most one fetch in flight, and that fetch includes every due change request of the forge. An open change request is polled every `activeIntervalMs` while checks are pending or mergeability is unknown, and every `idleIntervalMs` otherwise. Closed change requests use `idleIntervalMs` to detect reopening; merged requests stop automatic polling. `refresh(ref)` polls a watched change request at once, including after a terminal state; if a fetch is already in flight for its forge, another fetch starts immediately after it settles. A failed read repeats after `activeIntervalMs` doubled for each consecutive failure, up to `maxBackoffMs`, which must be at least `activeIntervalMs`. Unregistering a provider settles its watched change requests as `unavailable`. Polling stops when the last watcher leaves. The [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-forge) lists the defaults.
+
+Reaching `fetchTimeoutMs` aborts the fetch signal with `FORGE_FETCH_TIMEOUT`. Providers must stop their work and settle when the signal aborts; rejected fetches become `unavailable` failures. A provider that ignores cancellation can stall polling and service disposal.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+One timer covers all watched change requests. When it fires, the service groups due change requests by forge and starts one batched provider fetch per idle forge. A listener that throws is logged and skipped. Disposing the service aborts in-flight fetches and waits for them to settle.
+
+| Source | Responsibility |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Provider registration, URL mapping, watch lifetime, and batched polling |
+| [`src/schedule.ts`](src/schedule.ts) | Delay before the next poll of one change request |
+| [`src/keys.ts`](src/keys.ts) | Case-insensitive canonical identity of a change request |
+| [`src/types.ts`](src/types.ts) | Repository, change request, status, and provider types |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Forge subsystem](../../../docs/subsystems/forge.md) — provider contract, change request types, and service reference.
+- [GitHub provider](../forge-github/README.md) — the provider for GitHub hosts.
+- [Session bindings](../forge-session/README.md) — the consumer that binds change requests to Sessions.
+- [Binding decision](../../../.agents/notes/implemented/feature/2026-10-09-session-change-request-bindings.md) — why bindings derive from shell results and status stays on the host.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as providers and watchers exchange code host status without contributing model context.
+
+#### KV Cache effect
+
+None. No model request contains data from this package.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Polling only** — status reaches watchers on the next scheduled poll or `refresh`; there is no webhook intake.
+- **Process-local results** — latest results live in memory and are lost on restart; the next watcher polls again.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,100 @@
+---
+description: "通过一个提供方无关的服务注册代码托管提供方并轮询变更请求状态。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-experimental-forge
+
+[English](README.md) | 中文
+
+## 概述
+
+读取并操作 pull request 与 merge request，而不把消费方绑定到某一个代码托管平台。提供方把远端 URL 和变更请求（change request，即 pull request 或 merge request）URL 映射为提供方无关的引用，按 head 分支查找变更请求，批量读取其状态，读取其 diff 与文件，并按请求把草稿标记为可评审或合并变更请求。同一变更请求的所有监听方共享一个轮询循环，轮询节奏随检查、可合并性与生命周期状态变化。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [了解实现](#understand-the-implementation)
+- [深入探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与待办工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+将注册表与至少一个提供方包一起挂载，例如 GitHub 提供方。
+
+```yaml
+- name: '@deepseek-ai/dsh-experimental-forge'
+- name: '@deepseek-ai/dsh-experimental-forge-github'
+```
+
+`ctx.forge.register(provider)` 是调用方 fiber 上的 effect，返回异步 disposer，取消并等待该次注册的调用结束。取消后到达的结果会被丢弃。一个提供方服务一个 forge 家族；为同一家族注册第二个提供方会抛错。注册变化会发出 `forge/providers-changed`；注册提供方会立即轮询其已有监听。`repositoryFromRemote(url)` 与 `changeRequestFromUrl(url)` 按注册顺序询问提供方并返回第一个匹配结果。`changeRequestUrl(ref)`、`findByHead(repository, branch, signal)` 与 `readiness(repository, signal)` 委托给引用所属 forge 的提供方，没有注册提供方时抛错；`readiness` 报告提供方能否用当前凭据访问该主机。
+
+`markReady(ref, signal)` 把草稿标记为可评审；`merge(ref, { method, headSha }, signal)` 只在 head 仍是 `headSha` 时合并变更请求。两者都委托给引用所属 forge 的提供方，没有注册提供方时抛错；主机接受时 resolve 为 undefined，否则为 `ForgeActionFailure`：`unauthenticated`、head 已越过 `headSha` 时的 `stale`，或带主机原因的 `failed`。两者结束后，被监听的变更请求会立即重新轮询。快照带有 `mergeReady`（主机现在是否会为已登录用户合并该变更请求）与 `mergeMethods`（仓库接受的合并方式，该用户常用的方式排在最前）。
+
+`diff(ref, signal)` 读取托管平台计算出的变更请求统一补丁，路径带 `a/` 与 `b/` 前缀；`fileText(ref, commit, path, signal)` 读取其仓库中某个提交下的一个文件。两者都委托给引用所属 forge 的提供方，没有注册提供方时抛错，resolve 为文本或 `ForgeFailure`；托管平台或提供方因结果超过其大小上限而拒绝时，失败为 `too-large`。`fileUrl(ref, commit, path)` 返回该文件在该提交下的网页地址。
+
+`ctx.forge.watch(ref, listener)` 同样是 effect。变更请求的第一个监听方会立即触发轮询；`latest(ref)` 返回最近一次结果。每个 forge 同时最多只有一次读取在进行，这次读取包含该 forge 所有到期的变更请求。打开状态的变更请求在检查未完成或可合并性未知时每 `activeIntervalMs` 轮询一次，否则每 `idleIntervalMs` 轮询一次。已关闭的变更请求按 `idleIntervalMs` 轮询以检测重新打开；已合并的停止自动轮询。`refresh(ref)` 立即轮询一个被监听的变更请求，已结束的也包括在内；该 forge 已有读取在进行时，等待其结束后立即再读一次。读取失败后，重试间隔为 `activeIntervalMs` 按连续失败次数翻倍，最长 `maxBackoffMs`；该值必须大于或等于 `activeIntervalMs`。注销提供方会让其被监听的变更请求以 `unavailable` 结束。最后一个监听方离开后轮询停止。默认值见[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-forge)。
+
+达到 `fetchTimeoutMs` 时，读取信号会以 `FORGE_FETCH_TIMEOUT` 中止。提供方必须在信号中止时停止工作并结束请求；被拒绝的读取会转为 `unavailable` 失败。忽略取消的提供方可能阻塞轮询和服务销毁。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 了解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+一个定时器覆盖所有被监听的变更请求。定时器触发时，服务按 forge 对到期的变更请求分组，并为每个空闲的 forge 发起一次批量读取。抛错的监听方会被记录日志并跳过。销毁服务会中止进行中的读取，并等待它们结束。
+
+| 源码 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 提供方注册、URL 映射、监听生命周期与批量轮询 |
+| [`src/schedule.ts`](src/schedule.ts) | 计算单个变更请求距下次轮询的延迟 |
+| [`src/keys.ts`](src/keys.ts) | 变更请求不区分大小写的规范标识 |
+| [`src/types.ts`](src/types.ts) | 仓库、变更请求、状态与提供方类型 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 深入探索
+
+- [Forge 子系统](../../../docs/subsystems/forge.zh.md)——提供方契约、变更请求类型与服务参考。
+- [GitHub 提供方](../forge-github/README.zh.md)——服务 GitHub 主机的提供方。
+- [Session 绑定](../forge-session/README.zh.md)——把变更请求绑定到 Session 的消费方。
+- [绑定决策](../../../.agents/notes/implemented/feature/2026-10-09-session-change-request-bindings.zh.md)——为何绑定从 shell 结果派生、状态只留在宿主侧。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无：提供方与监听方只交换代码托管平台的状态，不贡献模型上下文。
+
+#### KV Cache 影响
+
+无。任何模型请求都不包含本包的数据。
+
+## 已知限制与待办工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **仅轮询**——状态在下一次计划轮询或 `refresh` 时才送达监听方；没有 webhook 接入。
+- **结果只在进程内**——最近结果保存在内存中，重启后丢失；下一个监听方会重新轮询。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,495 @@
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { MAX_TIMER_DELAY_MS, deadline } from "@deepseek-ai/dsh-timeout";
+import { brandString } from "@deepseek-ai/dsh-brand";
+//#region lib/types/keys.js
+/** Canonical identities for change requests. */
+/**
+* Build the canonical identity of a change request. Host, owner, and name
+* compare case-insensitively, as they do on the hosts this vocabulary serves.
+* @param ref - change request to identify.
+* @returns `<forge>:<host>/<owner>/<name>#<number>` in lowercase.
+*/
+function changeRequestKey(ref) {
+	const { forge, host, owner, name } = ref.repository;
+	return brandString(`${forge}:${host}/${owner}/${name}#${ref.number}`.toLowerCase());
+}
+//#endregion
+//#region lib/types/schedule.js
+/** Poll cadence for watched change requests. */
+/**
+* Choose the delay before the next poll of one change request. Failures back
+* off exponentially from the active interval; merged change requests stop
+* polling, while closed ones use the idle cadence to detect reopening.
+* @param result - latest snapshot or failure.
+* @param failures - consecutive failures, counting `result` when it is one.
+* @param intervals - configured cadence.
+* @returns the delay in milliseconds, or undefined after a terminal state.
+*/
+function nextPollDelay(result, failures, intervals) {
+	if ("code" in result) return Math.min(intervals.maxBackoffMs, intervals.activeIntervalMs * 2 ** failures);
+	if (result.state === "merged") return void 0;
+	if (result.state === "closed") return intervals.idleIntervalMs;
+	return result.checksRollup === "pending" || result.mergeability === "unknown" ? intervals.activeIntervalMs : intervals.idleIntervalMs;
+}
+//#endregion
+//#region lib/types/index.js
+/** Registry of code-host providers with provider-neutral change requests and shared status polling. */
+var __addDisposableResource = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
+};
+var __disposeResources = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/**
+* Registry of forge providers. Watchers of one change request share a single
+* polling loop; each forge has at most one fetch in flight, which batches
+* every due change request of that forge.
+*/
+var ForgeService = class extends Service {
+	static Config = z.object({
+		activeIntervalMs: z.number().default(3e4),
+		idleIntervalMs: z.number().default(12e4),
+		maxBackoffMs: z.number().default(6e5),
+		fetchTimeoutMs: z.number().default(3e4)
+	});
+	config;
+	providers = /* @__PURE__ */ new Map();
+	watches = /* @__PURE__ */ new Map();
+	fetching = /* @__PURE__ */ new Set();
+	pending = /* @__PURE__ */ new Set();
+	lifetime = new AbortController();
+	timer;
+	/**
+	* Poll what is due. A field rather than a method, so the timer runs it on
+	* the instance itself: a polling round started through a caller's `ctx.forge`
+	* would otherwise run on that caller's shadow receiver, and every later round
+	* would nest one more shadow until a property write overflows the stack.
+	*/
+	tick = () => {
+		this.timer = void 0;
+		this.poll();
+	};
+	constructor(ctx, config) {
+		super(ctx, "forge");
+		this.config = config;
+		for (const key of [
+			"activeIntervalMs",
+			"idleIntervalMs",
+			"maxBackoffMs",
+			"fetchTimeoutMs"
+		]) {
+			const value = this.config[key];
+			if (!Number.isSafeInteger(value) || value <= 0 || value > MAX_TIMER_DELAY_MS) throw new Error(`forge: ${key} must be a positive integer no greater than ${MAX_TIMER_DELAY_MS}`);
+		}
+		if (this.config.maxBackoffMs < this.config.activeIntervalMs) throw new Error("forge: maxBackoffMs must be greater than or equal to activeIntervalMs");
+		ctx.effect(() => async () => {
+			this.lifetime.abort(/* @__PURE__ */ new Error("forge service disposed"));
+			clearTimeout(this.timer);
+			this.timer = void 0;
+			await Promise.allSettled(this.pending);
+		}, "forge: stop polling");
+	}
+	/**
+	* Register the provider of one forge family as an effect on the calling
+	* fiber. Watches of that forge receive an `unavailable` failure when the
+	* registration ends. Unregistering cancels and awaits its in-flight calls;
+	* results from the withdrawn registration are discarded.
+	* @param provider - provider to serve `provider.forge`.
+	* @returns the disposer that unregisters the provider and waits for its calls to finish.
+	* @throws when another provider already serves the same forge.
+	*/
+	register(provider) {
+		const dispose = this.ctx.effect(() => {
+			if (this.providers.has(provider.forge)) throw new Error(`forge: a provider for "${provider.forge}" is already registered`);
+			const registration = {
+				provider,
+				lifetime: new AbortController(),
+				pending: /* @__PURE__ */ new Set()
+			};
+			this.providers.set(provider.forge, registration);
+			for (const watch of this.watches.values()) if (watch.ref.repository.forge === provider.forge) watch.dueAt = Date.now();
+			this.providersChanged(provider.forge);
+			this.schedule();
+			return async () => {
+				this.providers.delete(provider.forge);
+				registration.lifetime.abort(/* @__PURE__ */ new Error(`forge: provider "${provider.forge}" was unregistered`));
+				for (const watch of [...this.watches.values()]) if (watch.ref.repository.forge === provider.forge) this.settle(watch, this.missing(provider.forge), void 0);
+				this.providersChanged(provider.forge);
+				this.schedule();
+				await Promise.allSettled(registration.pending);
+			};
+		}, `forge.register(${provider.forge})`);
+		return async () => {
+			await dispose();
+		};
+	}
+	/**
+	* Map a Git remote URL to a repository through the first provider that serves it.
+	* @param url - fetch or push URL as Git reports it.
+	* @returns the repository, or undefined when no provider serves the URL.
+	*/
+	repositoryFromRemote(url) {
+		for (const { provider } of this.providers.values()) {
+			const repository = provider.repositoryFromRemote(url);
+			if (repository !== void 0) return repository;
+		}
+	}
+	/**
+	* Map a change request web URL through the first provider that serves it.
+	* @param url - web URL of a pull or merge request.
+	* @returns the change request, or undefined when no provider serves the URL.
+	*/
+	changeRequestFromUrl(url) {
+		for (const { provider } of this.providers.values()) {
+			const ref = provider.changeRequestFromUrl(url);
+			if (ref !== void 0) return ref;
+		}
+	}
+	/**
+	* Build the canonical web URL of a change request.
+	* @param ref - change request served by a registered provider.
+	* @returns the provider's canonical URL.
+	* @throws when no provider serves the change request's forge.
+	*/
+	changeRequestUrl(ref) {
+		return this.provider(ref.repository.forge).changeRequestUrl(ref);
+	}
+	/**
+	* Find open change requests whose head is `branch`, excluding the default branch and forks.
+	* @param repository - repository served by a registered provider.
+	* @param branch - head branch name on the host.
+	* @param signal - cancellation for the lookup.
+	* @returns matching change requests, newest first as the provider reports them.
+	* @throws when no provider serves the repository's forge or the lookup fails.
+	*/
+	async findByHead(repository, branch, signal) {
+		return await this.invoke(this.registration(repository.forge), signal, (provider, operation) => provider.findByHead(repository, branch, operation));
+	}
+	/**
+	* Report whether the provider can reach the repository's host with current credentials.
+	* @param repository - repository served by a registered provider.
+	* @param signal - cancellation for the probe.
+	* @returns the provider's readiness for the host.
+	* @throws when no provider serves the repository's forge.
+	*/
+	async readiness(repository, signal) {
+		return await this.invoke(this.registration(repository.forge), signal, (provider, operation) => provider.readiness(repository.host, operation));
+	}
+	/**
+	* Mark a draft change request ready for review, then poll it at once when it is watched.
+	* @param ref - change request served by a registered provider.
+	* @param signal - cancellation of the request.
+	* @returns undefined once the host accepted the change, or why it did not.
+	* @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
+	*/
+	async markReady(ref, signal) {
+		const failure = await this.invoke(this.registration(ref.repository.forge), signal, (provider, operation) => provider.markReady(ref, operation));
+		this.refresh(ref);
+		return failure;
+	}
+	/**
+	* Merge a change request while its head is still `request.headSha`, then
+	* poll it at once when it is watched.
+	* @param ref - change request served by a registered provider.
+	* @param request - merge method and the head commit the user confirmed.
+	* @param signal - cancellation of the request.
+	* @returns undefined once the host merged it, or why it did not.
+	* @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
+	*/
+	async merge(ref, request, signal) {
+		const failure = await this.invoke(this.registration(ref.repository.forge), signal, (provider, operation) => provider.merge(ref, request, operation));
+		this.refresh(ref);
+		return failure;
+	}
+	/**
+	* Read the changes of a change request as its host computes them.
+	* @param ref - change request served by a registered provider.
+	* @param signal - cancellation of the read.
+	* @returns one unified patch with `a/` and `b/` path prefixes, or why the host did not provide it.
+	* @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
+	*/
+	async diff(ref, signal) {
+		return await this.invoke(this.registration(ref.repository.forge), signal, (provider, operation) => provider.diff(ref, operation));
+	}
+	/**
+	* Read the text of one file at a commit of a change request's repository.
+	* @param ref - change request served by a registered provider.
+	* @param commit - commit object name.
+	* @param path - path relative to the repository root.
+	* @param signal - cancellation of the read.
+	* @returns the text, or why the host did not provide it.
+	* @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
+	*/
+	async fileText(ref, commit, path, signal) {
+		return await this.invoke(this.registration(ref.repository.forge), signal, (provider, operation) => provider.fileText(ref, commit, path, operation));
+	}
+	/**
+	* Build the web page of one file at a commit of a change request's repository.
+	* @param ref - change request served by a registered provider.
+	* @param commit - commit object name.
+	* @param path - path relative to the repository root.
+	* @returns the provider's URL.
+	* @throws when no provider serves the change request's forge.
+	*/
+	fileUrl(ref, commit, path) {
+		return this.provider(ref.repository.forge).fileUrl(ref, commit, path);
+	}
+	/**
+	* Watch one change request as an effect on the calling fiber. The first
+	* watcher starts polling at once; listeners receive every later result,
+	* and `latest` returns the current one. Polling stops when the last watcher
+	* leaves. Listeners must not throw; a thrown error is logged and skipped.
+	* @param ref - change request to poll.
+	* @param listener - receives each polling result.
+	* @returns the disposer that stops this watch.
+	*/
+	watch(ref, listener) {
+		const key = changeRequestKey(ref);
+		const dispose = this.ctx.effect(() => {
+			let watch = this.watches.get(key);
+			if (watch === void 0) {
+				watch = {
+					key,
+					ref,
+					listeners: /* @__PURE__ */ new Set(),
+					latest: void 0,
+					dueAt: Date.now(),
+					failures: 0
+				};
+				this.watches.set(key, watch);
+				this.schedule();
+			}
+			const owned = watch;
+			owned.listeners.add(listener);
+			return () => {
+				owned.listeners.delete(listener);
+				if (owned.listeners.size === 0 && this.watches.get(key) === owned) {
+					this.watches.delete(key);
+					this.schedule();
+				}
+			};
+		}, "forge.watch()");
+		return () => void dispose();
+	}
+	/**
+	* Poll a watched change request at once, including after a terminal state.
+	* A fetch already in flight is followed immediately by another fetch; an
+	* unwatched change request is unchanged.
+	* @param ref - change request to poll.
+	*/
+	refresh(ref) {
+		const watch = this.watches.get(changeRequestKey(ref));
+		if (watch === void 0) return;
+		watch.dueAt = Date.now();
+		this.schedule();
+	}
+	/**
+	* Read the latest polling result of a watched change request.
+	* @param ref - change request to read.
+	* @returns the latest result, or undefined before the first result or without a watch.
+	*/
+	latest(ref) {
+		return this.watches.get(changeRequestKey(ref))?.latest;
+	}
+	provider(forge) {
+		return this.registration(forge).provider;
+	}
+	providersChanged(forge) {
+		if (this.lifetime.signal.aborted) return;
+		const task = this.ctx.parallel("forge/providers-changed", forge).catch((error) => {
+			this.ctx.logger.warn(`forge: provider change listener failed: ${String(error)}`);
+		});
+		this.pending.add(task);
+		task.then(() => this.pending.delete(task));
+	}
+	registration(forge) {
+		const registration = this.providers.get(forge);
+		if (registration === void 0) throw new Error(`forge: ${this.missing(forge).message}`);
+		return registration;
+	}
+	async invoke(registration, signal, action) {
+		const operation = AbortSignal.any([
+			signal,
+			this.lifetime.signal,
+			registration.lifetime.signal
+		]);
+		operation.throwIfAborted();
+		const completion = Promise.withResolvers();
+		registration.pending.add(completion.promise);
+		this.pending.add(completion.promise);
+		try {
+			const result = await action(registration.provider, operation);
+			operation.throwIfAborted();
+			return result;
+		} finally {
+			registration.pending.delete(completion.promise);
+			this.pending.delete(completion.promise);
+			completion.resolve();
+		}
+	}
+	missing(forge) {
+		return {
+			code: "unavailable",
+			message: `no provider is registered for "${forge}"`
+		};
+	}
+	schedule() {
+		clearTimeout(this.timer);
+		this.timer = void 0;
+		if (this.lifetime.signal.aborted) return;
+		let next;
+		for (const watch of this.watches.values()) {
+			if (watch.dueAt === void 0 || this.fetching.has(watch.ref.repository.forge)) continue;
+			next = next === void 0 ? watch.dueAt : Math.min(next, watch.dueAt);
+		}
+		if (next === void 0) return;
+		this.timer = setTimeout(this.tick, Math.max(0, next - Date.now()));
+	}
+	poll() {
+		const now = Date.now();
+		const due = /* @__PURE__ */ new Map();
+		for (const watch of this.watches.values()) {
+			const forge = watch.ref.repository.forge;
+			if (watch.dueAt === void 0 || watch.dueAt > now || this.fetching.has(forge)) continue;
+			const batch = due.get(forge);
+			if (batch === void 0) due.set(forge, [watch]);
+			else batch.push(watch);
+		}
+		for (const [forge, batch] of due) {
+			const task = this.fetch(forge, batch);
+			this.pending.add(task);
+			task.then(() => this.pending.delete(task));
+		}
+		this.schedule();
+	}
+	/** Fetch one forge's batch; never rejects. */
+	async fetch(forge, batch) {
+		this.fetching.add(forge);
+		for (const watch of batch) watch.dueAt = void 0;
+		let results;
+		let failure;
+		const registration = this.providers.get(forge);
+		try {
+			if (registration === void 0) failure = this.missing(forge);
+			else {
+				const env_1 = {
+					stack: [],
+					error: void 0,
+					hasError: false
+				};
+				try {
+					const timeout = __addDisposableResource(env_1, deadline(this.lifetime.signal, this.config.fetchTimeoutMs, "FORGE_FETCH_TIMEOUT"), false);
+					results = await this.invoke(registration, timeout.signal, (provider, operation) => provider.fetch(batch.map((watch) => watch.ref), operation));
+				} catch (e_1) {
+					env_1.error = e_1;
+					env_1.hasError = true;
+				} finally {
+					__disposeResources(env_1);
+				}
+			}
+		} catch (error) {
+			failure = {
+				code: "unavailable",
+				message: error instanceof Error ? error.message : String(error)
+			};
+		} finally {
+			this.fetching.delete(forge);
+		}
+		if (this.lifetime.signal.aborted) return;
+		if (registration !== this.providers.get(forge)) {
+			this.schedule();
+			return;
+		}
+		for (const watch of batch) {
+			if (this.watches.get(watch.key) !== watch) continue;
+			const result = failure ?? results?.get(watch.key) ?? {
+				code: "unavailable",
+				message: `provider returned no result for ${watch.key}`
+			};
+			this.settle(watch, result, watch.dueAt);
+		}
+		this.schedule();
+	}
+	settle(watch, result, refreshAt) {
+		const fetchedAt = Date.now();
+		let update;
+		if ("code" in result) {
+			watch.failures++;
+			update = {
+				key: watch.key,
+				fetchedAt,
+				failure: result
+			};
+		} else {
+			watch.failures = 0;
+			update = {
+				key: watch.key,
+				fetchedAt,
+				snapshot: result
+			};
+		}
+		watch.latest = update;
+		const delay = nextPollDelay(result, watch.failures, this.config);
+		watch.dueAt = refreshAt ?? (delay === void 0 ? void 0 : fetchedAt + delay);
+		for (const listener of [...watch.listeners]) try {
+			listener(update);
+		} catch (error) {
+			this.ctx.logger.warn(`forge: change request listener failed: ${String(error)}`);
+		}
+	}
+};
+//#endregion
+export { ForgeService, ForgeService as default, changeRequestKey };

package/lib/types/index.d.ts

@@ -0,0 +1,169 @@
+/** Registry of code-host providers with provider-neutral change requests and shared status polling. */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ChangeRequestListener, ChangeRequestRef, ChangeRequestUpdate, Config, ForgeActionFailure, ForgeFailure, ForgeProvider, ForgeReadiness, ForgeRepository, MergeRequest } from './types.ts';
+export { changeRequestKey } from './keys.ts';
+export type * from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        forge: ForgeService;
+    }
+    interface Events {
+        /**
+         * Announces a provider registration or withdrawal after the registry changes.
+         * Listener failures are logged without preventing other listeners from running.
+         * @param forge - family whose provider changed.
+         * @mode parallel
+         */
+        'forge/providers-changed'(forge: string): void | Promise<void>;
+    }
+}
+/**
+ * Registry of forge providers. Watchers of one change request share a single
+ * polling loop; each forge has at most one fetch in flight, which batches
+ * every due change request of that forge.
+ */
+export declare class ForgeService extends Service {
+    static Config: z<Config>;
+    private readonly config;
+    private readonly providers;
+    private readonly watches;
+    private readonly fetching;
+    private readonly pending;
+    private readonly lifetime;
+    private timer;
+    /**
+     * Poll what is due. A field rather than a method, so the timer runs it on
+     * the instance itself: a polling round started through a caller's `ctx.forge`
+     * would otherwise run on that caller's shadow receiver, and every later round
+     * would nest one more shadow until a property write overflows the stack.
+     */
+    private readonly tick;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Register the provider of one forge family as an effect on the calling
+     * fiber. Watches of that forge receive an `unavailable` failure when the
+     * registration ends. Unregistering cancels and awaits its in-flight calls;
+     * results from the withdrawn registration are discarded.
+     * @param provider - provider to serve `provider.forge`.
+     * @returns the disposer that unregisters the provider and waits for its calls to finish.
+     * @throws when another provider already serves the same forge.
+     */
+    register(provider: ForgeProvider): () => Promise<void>;
+    /**
+     * Map a Git remote URL to a repository through the first provider that serves it.
+     * @param url - fetch or push URL as Git reports it.
+     * @returns the repository, or undefined when no provider serves the URL.
+     */
+    repositoryFromRemote(url: string): ForgeRepository | undefined;
+    /**
+     * Map a change request web URL through the first provider that serves it.
+     * @param url - web URL of a pull or merge request.
+     * @returns the change request, or undefined when no provider serves the URL.
+     */
+    changeRequestFromUrl(url: string): ChangeRequestRef | undefined;
+    /**
+     * Build the canonical web URL of a change request.
+     * @param ref - change request served by a registered provider.
+     * @returns the provider's canonical URL.
+     * @throws when no provider serves the change request's forge.
+     */
+    changeRequestUrl(ref: ChangeRequestRef): string;
+    /**
+     * Find open change requests whose head is `branch`, excluding the default branch and forks.
+     * @param repository - repository served by a registered provider.
+     * @param branch - head branch name on the host.
+     * @param signal - cancellation for the lookup.
+     * @returns matching change requests, newest first as the provider reports them.
+     * @throws when no provider serves the repository's forge or the lookup fails.
+     */
+    findByHead(repository: ForgeRepository, branch: string, signal: AbortSignal): Promise<readonly ChangeRequestRef[]>;
+    /**
+     * Report whether the provider can reach the repository's host with current credentials.
+     * @param repository - repository served by a registered provider.
+     * @param signal - cancellation for the probe.
+     * @returns the provider's readiness for the host.
+     * @throws when no provider serves the repository's forge.
+     */
+    readiness(repository: ForgeRepository, signal: AbortSignal): Promise<ForgeReadiness>;
+    /**
+     * Mark a draft change request ready for review, then poll it at once when it is watched.
+     * @param ref - change request served by a registered provider.
+     * @param signal - cancellation of the request.
+     * @returns undefined once the host accepted the change, or why it did not.
+     * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
+     */
+    markReady(ref: ChangeRequestRef, signal: AbortSignal): Promise<ForgeActionFailure | undefined>;
+    /**
+     * Merge a change request while its head is still `request.headSha`, then
+     * poll it at once when it is watched.
+     * @param ref - change request served by a registered provider.
+     * @param request - merge method and the head commit the user confirmed.
+     * @param signal - cancellation of the request.
+     * @returns undefined once the host merged it, or why it did not.
+     * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
+     */
+    merge(ref: ChangeRequestRef, request: MergeRequest, signal: AbortSignal): Promise<ForgeActionFailure | undefined>;
+    /**
+     * Read the changes of a change request as its host computes them.
+     * @param ref - change request served by a registered provider.
+     * @param signal - cancellation of the read.
+     * @returns one unified patch with `a/` and `b/` path prefixes, or why the host did not provide it.
+     * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
+     */
+    diff(ref: ChangeRequestRef, signal: AbortSignal): Promise<string | ForgeFailure>;
+    /**
+     * Read the text of one file at a commit of a change request's repository.
+     * @param ref - change request served by a registered provider.
+     * @param commit - commit object name.
+     * @param path - path relative to the repository root.
+     * @param signal - cancellation of the read.
+     * @returns the text, or why the host did not provide it.
+     * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
+     */
+    fileText(ref: ChangeRequestRef, commit: string, path: string, signal: AbortSignal): Promise<string | ForgeFailure>;
+    /**
+     * Build the web page of one file at a commit of a change request's repository.
+     * @param ref - change request served by a registered provider.
+     * @param commit - commit object name.
+     * @param path - path relative to the repository root.
+     * @returns the provider's URL.
+     * @throws when no provider serves the change request's forge.
+     */
+    fileUrl(ref: ChangeRequestRef, commit: string, path: string): string;
+    /**
+     * Watch one change request as an effect on the calling fiber. The first
+     * watcher starts polling at once; listeners receive every later result,
+     * and `latest` returns the current one. Polling stops when the last watcher
+     * leaves. Listeners must not throw; a thrown error is logged and skipped.
+     * @param ref - change request to poll.
+     * @param listener - receives each polling result.
+     * @returns the disposer that stops this watch.
+     */
+    watch(ref: ChangeRequestRef, listener: ChangeRequestListener): () => void;
+    /**
+     * Poll a watched change request at once, including after a terminal state.
+     * A fetch already in flight is followed immediately by another fetch; an
+     * unwatched change request is unchanged.
+     * @param ref - change request to poll.
+     */
+    refresh(ref: ChangeRequestRef): void;
+    /**
+     * Read the latest polling result of a watched change request.
+     * @param ref - change request to read.
+     * @returns the latest result, or undefined before the first result or without a watch.
+     */
+    latest(ref: ChangeRequestRef): ChangeRequestUpdate | undefined;
+    private provider;
+    private providersChanged;
+    private registration;
+    private invoke;
+    private missing;
+    private schedule;
+    private poll;
+    /** Fetch one forge's batch; never rejects. */
+    private fetch;
+    private settle;
+}
+export default ForgeService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/keys.d.ts

@@ -0,0 +1,10 @@
+/** Canonical identities for change requests. */
+import type { ChangeRequestKey, ChangeRequestRef } from './types.ts';
+/**
+ * Build the canonical identity of a change request. Host, owner, and name
+ * compare case-insensitively, as they do on the hosts this vocabulary serves.
+ * @param ref - change request to identify.
+ * @returns `<forge>:<host>/<owner>/<name>#<number>` in lowercase.
+ */
+export declare function changeRequestKey(ref: ChangeRequestRef): ChangeRequestKey;
+//# sourceMappingURL=keys.d.ts.map

package/lib/types/schedule.d.ts

@@ -0,0 +1,22 @@
+/** Poll cadence for watched change requests. */
+import type { ChangeRequestSnapshot, ForgeFailure } from './types.ts';
+/** Resolved intervals that pace polling. */
+export interface PollIntervals {
+    /** Delay while checks run or mergeability is unknown. */
+    readonly activeIntervalMs: number;
+    /** Delay for a closed request or an open request whose checks have settled. */
+    readonly idleIntervalMs: number;
+    /** Largest delay after consecutive failures. */
+    readonly maxBackoffMs: number;
+}
+/**
+ * Choose the delay before the next poll of one change request. Failures back
+ * off exponentially from the active interval; merged change requests stop
+ * polling, while closed ones use the idle cadence to detect reopening.
+ * @param result - latest snapshot or failure.
+ * @param failures - consecutive failures, counting `result` when it is one.
+ * @param intervals - configured cadence.
+ * @returns the delay in milliseconds, or undefined after a terminal state.
+ */
+export declare function nextPollDelay(result: ChangeRequestSnapshot | ForgeFailure, failures: number, intervals: PollIntervals): number | undefined;
+//# sourceMappingURL=schedule.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,192 @@
+/** Provider-neutral vocabulary for code hosts, their change requests, and provider contracts. */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+/** One repository on a code host, identified the way its provider addresses it. */
+export interface ForgeRepository {
+    /** Provider family that serves the repository, such as `github`. */
+    readonly forge: string;
+    /** Lowercase host name, such as `github.com`. */
+    readonly host: string;
+    /** Owner or namespace path as the host spells it. */
+    readonly owner: string;
+    /** Repository name as the host spells it. */
+    readonly name: string;
+}
+/** One change request (pull request or merge request) in a repository. */
+export interface ChangeRequestRef {
+    /** Repository that holds the change request. */
+    readonly repository: ForgeRepository;
+    /** Host-assigned change request number. */
+    readonly number: number;
+}
+/** Canonical identity of a change request across providers; built by `changeRequestKey`. */
+export type ChangeRequestKey = Branded<'ChangeRequestKey'>;
+/** Lifecycle state of a change request. */
+export type ChangeRequestState = 'open' | 'closed' | 'merged';
+/** Normalized outcome of one status check. */
+export type CheckState = 'pending' | 'success' | 'failure' | 'neutral' | 'skipped' | 'cancelled';
+/** One status check reported for the head commit of a change request. */
+export interface ChangeRequestCheck {
+    /** Check name as the host displays it. */
+    readonly name: string;
+    /** Normalized check outcome. */
+    readonly state: CheckState;
+    /** Web page for the check, or null when the host reports none. */
+    readonly url: string | null;
+    /** Workflow that produced the check, or null when the host reports none. */
+    readonly workflow: string | null;
+    /** ISO 8601 time the check started, or null before it starts and when the host reports none. */
+    readonly startedAt: string | null;
+    /** ISO 8601 time the check completed, or null while it runs and when the host reports none. */
+    readonly completedAt: string | null;
+}
+/** Combined outcome of all checks on the head commit. */
+export type ChecksRollup = 'none' | 'pending' | 'success' | 'failure';
+/** Whether the change request can merge into its base without conflicts. */
+export type Mergeability = 'mergeable' | 'conflicting' | 'unknown';
+/** Aggregate review outcome required by the host's merge rules. */
+export type ReviewDecision = 'approved' | 'changes-requested' | 'review-required' | 'none';
+/** How a merge brings the commits of a change request into its base branch. */
+export type MergeMethod = 'merge' | 'squash' | 'rebase';
+/** Status of one change request at the time its provider read it. */
+export interface ChangeRequestSnapshot {
+    /** Change request the snapshot describes. */
+    readonly ref: ChangeRequestRef;
+    /** Web page of the change request. */
+    readonly url: string;
+    /** Title as the author wrote it. */
+    readonly title: string;
+    /** Lifecycle state. */
+    readonly state: ChangeRequestState;
+    /** Whether the author marked the change request as a draft. */
+    readonly draft: boolean;
+    /** Author login, or null when the host hides it. */
+    readonly author: string | null;
+    /** Branch that carries the proposed commits. */
+    readonly headBranch: string;
+    /** Commit object name at the head of the change request. */
+    readonly headSha: string;
+    /** Branch the change request merges into. */
+    readonly baseBranch: string;
+    /** Lines the change request adds. */
+    readonly additions: number;
+    /** Lines the change request deletes. */
+    readonly deletions: number;
+    /** Merge conflict status; `unknown` while the host computes it. */
+    readonly mergeability: Mergeability;
+    /**
+     * Whether the host would merge the change request now for the signed-in
+     * user: open, not a draft, and meeting the base branch's merge rules.
+     */
+    readonly mergeReady: boolean;
+    /** Merge methods the repository accepts, the signed-in user's usual one first. */
+    readonly mergeMethods: readonly MergeMethod[];
+    /** Aggregate review outcome. */
+    readonly reviewDecision: ReviewDecision;
+    /** Checks on the head commit in host order. */
+    readonly checks: readonly ChangeRequestCheck[];
+    /** Combined check outcome. */
+    readonly checksRollup: ChecksRollup;
+    /** Whether the host reported more checks than `checks` contains. */
+    readonly checksTruncated: boolean;
+    /** Number of review threads that are not resolved. */
+    readonly unresolvedThreads: number;
+    /** ISO 8601 time of the host's last update to the change request. */
+    readonly updatedAt: string;
+    /** ISO 8601 time the change request was merged or closed, or null while it is open. */
+    readonly closedAt: string | null;
+}
+/** Why a provider could not read a change request. */
+export interface ForgeFailure {
+    /**
+     * `not-found`: the host does not expose it; `unauthenticated`: credentials are missing or rejected;
+     * `too-large`: the host or the provider refuses an answer over its size limit, so reading again fails
+     * the same way; `unavailable`: any other failure.
+     */
+    readonly code: 'not-found' | 'unauthenticated' | 'too-large' | 'unavailable';
+    /** Human-readable cause. */
+    readonly message: string;
+}
+/** Latest polling result delivered to watchers of one change request. */
+export type ChangeRequestUpdate = {
+    /** Canonical identity of the watched change request. */
+    readonly key: ChangeRequestKey;
+    /** Epoch milliseconds when the result settled. */
+    readonly fetchedAt: number;
+} & ({
+    /** Status read from the host. */
+    readonly snapshot: ChangeRequestSnapshot;
+} | {
+    /** Reason the status could not be read. */
+    readonly failure: ForgeFailure;
+});
+/** A merge the user confirmed for the head commit they saw. */
+export interface MergeRequest {
+    /** How the commits enter the base branch. */
+    readonly method: MergeMethod;
+    /** Commit object name the head must still have; the merge is refused once the head moves. */
+    readonly headSha: string;
+}
+/** Why a provider could not change a change request. */
+export interface ForgeActionFailure {
+    /**
+     * `unauthenticated`: credentials are missing or rejected; `stale`: the head
+     * moved past the confirmed commit; `failed`: the host refused or could not be reached.
+     */
+    readonly code: 'unauthenticated' | 'stale' | 'failed';
+    /** Human-readable cause, usually the host's own message. */
+    readonly message: string;
+}
+/** Whether a provider can reach one host with the current credentials. */
+export interface ForgeReadiness {
+    /** `ready`, `unauthenticated` (sign-in needed), or `unavailable` (tool missing or host unreachable). */
+    readonly state: 'ready' | 'unauthenticated' | 'unavailable';
+    /** Human-readable detail, or null when ready. */
+    readonly message: string | null;
+}
+/**
+ * Host-specific access registered with `ctx.forge`. One provider serves one
+ * forge family; methods that take a signal must stop work when it aborts.
+ */
+export interface ForgeProvider {
+    /** Forge family name stored in every repository this provider returns. */
+    readonly forge: string;
+    /** Map a Git remote URL to its repository, or undefined when this provider does not serve it. */
+    repositoryFromRemote(url: string): ForgeRepository | undefined;
+    /** Map a change request web URL to its reference, or undefined when this provider does not serve it. */
+    changeRequestFromUrl(url: string): ChangeRequestRef | undefined;
+    /** Build the canonical web URL of a change request this provider serves. */
+    changeRequestUrl(ref: ChangeRequestRef): string;
+    /** Read the status of several change requests, returning one result per requested key. */
+    fetch(refs: readonly ChangeRequestRef[], signal: AbortSignal): Promise<ReadonlyMap<ChangeRequestKey, ChangeRequestSnapshot | ForgeFailure>>;
+    /** Find open change requests whose head is `branch` in `repository`, excluding the default branch and forks. */
+    findByHead(repository: ForgeRepository, branch: string, signal: AbortSignal): Promise<readonly ChangeRequestRef[]>;
+    /** Report whether the provider can reach `host` with current credentials. */
+    readiness(host: string, signal: AbortSignal): Promise<ForgeReadiness>;
+    /** Mark a draft change request ready for review, resolving to undefined once the host accepted it. */
+    markReady(ref: ChangeRequestRef, signal: AbortSignal): Promise<ForgeActionFailure | undefined>;
+    /** Merge a change request while its head is still `request.headSha`, resolving to undefined once merged. */
+    merge(ref: ChangeRequestRef, request: MergeRequest, signal: AbortSignal): Promise<ForgeActionFailure | undefined>;
+    /** Read the changes of a change request as the host computes them, as one unified patch with `a/` and `b/` path prefixes. */
+    diff(ref: ChangeRequestRef, signal: AbortSignal): Promise<string | ForgeFailure>;
+    /** Read the text of `path` at `commit` in the change request's repository. */
+    fileText(ref: ChangeRequestRef, commit: string, path: string, signal: AbortSignal): Promise<string | ForgeFailure>;
+    /** Build the web page of `path` at `commit` in the change request's repository. */
+    fileUrl(ref: ChangeRequestRef, commit: string, path: string): string;
+}
+/**
+ * Receives every polling result for one watched change request.
+ * @param update - the settled result.
+ */
+export type ChangeRequestListener = (update: ChangeRequestUpdate) => void;
+/** Poll cadence and fetch deadline for watched change requests. */
+export interface Config {
+    /** Poll interval in milliseconds while checks run or mergeability is unknown. */
+    activeIntervalMs?: number;
+    /** Poll interval in milliseconds for a closed request or an open request whose checks have settled. */
+    idleIntervalMs?: number;
+    /** Largest delay in milliseconds between polls after consecutive failures. */
+    maxBackoffMs?: number;
+    /** Deadline in milliseconds for one provider fetch. */
+    fetchTimeoutMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/locale/de.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Änderungsanfragen",
+    "description": "Registrieren Sie Code-Hosting-Anbieter und fragen Sie den Status von Änderungsanfragen regelmäßig über einen anbieterneutralen Dienst ab."
+  }
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Change requests",
+    "description": "Register code host providers and poll change request status through one provider-neutral service."
+  }
+}

package/locale/es.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Solicitudes de cambio",
+    "description": "Registre proveedores de alojamiento de código y consulte periódicamente el estado de las solicitudes de cambio mediante un único servicio independiente del proveedor."
+  }
+}

package/locale/fr.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Demandes de modification",
+    "description": "Enregistrez des fournisseurs d'hébergement de code et interrogez régulièrement l'état des demandes de modification via un seul service indépendant du fournisseur."
+  }
+}

package/locale/ja.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "変更リクエスト",
+    "description": "プロバイダーに依存しない 1 つのサービスで、コードホストのプロバイダーを登録し、変更リクエストの状態をポーリングします。"
+  }
+}

package/locale/pt.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Solicitações de alteração",
+    "description": "Registre provedores de hospedagem de código e consulte periodicamente o status das solicitações de alteração por meio de um único serviço independente de provedor."
+  }
+}

package/locale/ru.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Запросы на изменение",
+    "description": "Зарегистрируйте провайдеров хостинга кода и опрашивайте статус запросов на изменение через единый сервис, не зависящий от провайдера."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "变更请求",
+    "description": "通过一个与提供方无关的服务注册代码托管提供方，并轮询变更请求状态。"
+  }
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@deepseek-ai/dsh-experimental-forge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Provider-neutral change request registry with shared status polling",
+  "version": "0.2.2-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts"
+    },
+    "./locale/*.json": "./locale/*.json",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "locale/*.json",
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/experimental/forge"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.6-alpha.1",
+    "@deepseek-ai/dsh-brand": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-timeout": "0.2.2-alpha.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.6-alpha.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.6-alpha.1"
+  }
 }