diff --git a/AGENTS.md b/AGENTS.md index b39dd1e..2db4ad3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # code.hybscloud.com/uring Agent Guide -This is the entry point to the guide set for using `code.hybscloud.com/uring` correctly. Use it when generating or reviewing caller-side code above or beyond the package boundary: runtimes, protocol stacks, services, and review work that needs a precise Linux `io_uring` boundary. +This is the entry point to the guide set for using `code.hybscloud.com/uring` correctly. Use it when generating or reviewing caller-side code around the package boundary: runtimes, protocol stacks, services, and review work that needs a precise Linux `io_uring` boundary. Read [`uring/README.md`](README.md) first for the package overview and API examples. Then use this guide to decide which facts belong at the boundary, which policy belongs in the caller layer, and which lifecycle transitions must remain visible. @@ -10,7 +10,7 @@ Treat `code.hybscloud.com/uring` as a narrow Linux `io_uring` boundary. It sets Keep caller policy in the layer that invokes `code.hybscloud.com/uring`: retry/backoff, poll cadence, scheduling, parking, routing, route retirement, parser state, protocol branching, completion routing, cancellation and timeout policy, safety checks, and service lifecycle. Use this guide for caller-side design and review, not as a package-maintenance manual. -The `INDEX.md` files under [`agents/`](agents/) are readable navigation: use them to choose the guide files required by a task. [`agents/references.md`](agents/references.md) is a natural-language research guide, and the [`agents/workflow/`](agents/workflow/) files are readable procedure — the gates, obligations, checklists, and staged loop you apply to a task. The remaining topic files under `boundary/`, `formalization/`, `lift/`, and `runtime/` carry the formal notation for tasks that need it, including abstraction from caller-side Go into the guide notation and compilation from checked notation back into Go, for both the layer directly above the package and the broader systems beyond it. Theory terms in those files are useful only when they classify a concrete guide obligation: effect and resumption, context and coeffect, session frontier, runner observation, denotation, compilation, or verification evidence. This file is the readable entrypoint. +The `INDEX.md` files under [`agents/`](agents/) are readable navigation: use them to choose the guide files required by a task. [`agents/references.md`](agents/references.md) is a natural-language research guide, and the [`agents/workflow/`](agents/workflow/) files are readable procedure: the gates, obligations, checklists, and staged loop you apply to a task. The remaining topic files under `boundary/`, `formalization/`, `lift/`, and `runtime/` carry the formal notation for tasks that need it, including abstraction from caller-side Go into the guide notation and compilation from checked notation back into Go. Theory terms in those files are useful only when they classify a concrete guide obligation: effect and resumption, context and coeffect, session frontier, runner observation, denotation, compilation, or verification evidence. This file is the readable entrypoint. ```text beyond code.hybscloud.com/uring = broader systems built on the layer above: protocol stacks, services, applications diff --git a/README.es.md b/README.es.md index 8fa62d2..06f82ba 100644 --- a/README.es.md +++ b/README.es.md @@ -47,9 +47,9 @@ La rama estable de Debian 13 incluye el kernel 6.12. La suite `trixie-backports` La creación del ring puede devolver `ENOMEM`, `EPERM` o `ENOSYS` según los límites de memlock, la configuración de sysctl o el soporte del kernel. Los entornos de ejecución de contenedores bloquean las llamadas al sistema de `io_uring` por defecto. Consulte [SETUP.md](./SETUP.md) para el diagnóstico y la resolución. -## Codificación orientada a agentes sobre o más allá de `code.hybscloud.com/uring` +## Codificación orientada a agentes alrededor de la frontera `code.hybscloud.com/uring` -Utilice el punto de entrada de la guía independiente [`AGENTS.md`](./AGENTS.md) al generar o revisar código del llamador sobre o más allá de `code.hybscloud.com/uring`. Use [`agents/INDEX.md`](./agents/INDEX.md) como índice de temas para conservar la frontera del núcleo: mecánica SQE/CQE, identidad en `user_data`, propiedad de búferes, resultados de finalización, reglas de ciclo de vida, límites de integración, comprobaciones de referencia y el flujo desde análisis y formalización hasta razonamiento, compilación a Go y verificación. +Utilice el punto de entrada de la guía independiente [`AGENTS.md`](./AGENTS.md) al generar o revisar código del llamador alrededor de la frontera `code.hybscloud.com/uring`: runtimes, pilas de protocolos, servicios y trabajos de revisión que necesitan una frontera Linux `io_uring` precisa. Use [`agents/INDEX.md`](./agents/INDEX.md) como índice de temas para conservar la frontera del núcleo: mecánica SQE/CQE, identidad en `user_data`, propiedad de búferes, resultados de finalización, reglas de ciclo de vida, límites de integración, comprobaciones de referencia y el flujo desde análisis y formalización hasta razonamiento, compilación a Go y verificación. La regla es simple: `code.hybscloud.com/uring` expone hechos del núcleo; las capas del llamador eligen la política. Mantenga reintentos/backoff, cadencia de sondeo, planificación, enrutamiento, retirada de rutas, estado de protocolo, análisis sintáctico, enrutamiento de finalizaciones, política de cancelación y tiempo de espera, comprobaciones de seguridad y ciclo de vida del servicio fuera de la frontera de `code.hybscloud.com/uring`, y conserve visibles `ErrWouldBlock`, `ErrMore`, `IORING_CQE_F_MORE`, la transferencia de propiedad y los fallos de capacidad. diff --git a/README.fr.md b/README.fr.md index 5a5d396..f96c85f 100644 --- a/README.fr.md +++ b/README.fr.md @@ -47,9 +47,9 @@ La branche stable de Debian 13 fournit le noyau 6.12. La suite `trixie-backports La création du ring peut renvoyer `ENOMEM`, `EPERM` ou `ENOSYS` selon les limites memlock, la configuration sysctl ou le support noyau. Les environnements d'exécution de conteneurs bloquent par défaut les appels système `io_uring`. Consultez [SETUP.md](./SETUP.md) pour le diagnostic et la résolution. -## Codage agentique au-dessus ou au-delà de `code.hybscloud.com/uring` +## Codage agentique autour de la frontière `code.hybscloud.com/uring` -Utilisez le point d'entrée du guide autonome [`AGENTS.md`](./AGENTS.md) lorsque vous générez ou relisez du code appelant au-dessus ou au-delà de `code.hybscloud.com/uring`. Utilisez [`agents/INDEX.md`](./agents/INDEX.md) comme index thématique afin de préserver la frontière noyau : mécanique SQE/CQE, identité `user_data`, propriété des tampons, résultats de complétion, règles de cycle de vie, limites d'intégration, contrôles de référence et le flux depuis l'analyse et la formalisation jusqu'au raisonnement, à la compilation vers Go et à la vérification. +Utilisez le point d'entrée du guide autonome [`AGENTS.md`](./AGENTS.md) lorsque vous générez ou relisez du code appelant autour de la frontière `code.hybscloud.com/uring` : runtimes, piles de protocoles, services et travaux de revue qui exigent une frontière Linux `io_uring` précise. Utilisez [`agents/INDEX.md`](./agents/INDEX.md) comme index thématique afin de préserver la frontière noyau : mécanique SQE/CQE, identité `user_data`, propriété des tampons, résultats de complétion, règles de cycle de vie, limites d'intégration, contrôles de référence et le flux depuis l'analyse et la formalisation jusqu'au raisonnement, à la compilation vers Go et à la vérification. La règle est simple : `code.hybscloud.com/uring` expose les faits noyau ; les couches appelantes choisissent la politique. Laissez les reprises/backoff, la cadence de polling, l'ordonnancement, le routage, le retrait des routes, l'état de protocole, l'analyse syntaxique, le routage des complétions, les politiques d'annulation et de délai, les contrôles de sécurité et le cycle de vie du service hors de la frontière de `code.hybscloud.com/uring`, et gardez visibles `ErrWouldBlock`, `ErrMore`, `IORING_CQE_F_MORE`, le transfert de propriété et les échecs de capacité. diff --git a/README.ja.md b/README.ja.md index 88e1b00..e9e0790 100644 --- a/README.ja.md +++ b/README.ja.md @@ -47,9 +47,9 @@ Debian 13 の安定版トラックが提供するカーネルは 6.12 です。` リング生成時に `ENOMEM`・`EPERM`・`ENOSYS` が返る場合、memlock 上限、sysctl 設定、またはカーネルのサポート状況が原因です。コンテナランタイムはデフォルトで `io_uring` システムコールをブロックします。診断と解決手順は [SETUP.md](./SETUP.md) を参照してください。 -## `code.hybscloud.com/uring` の上位およびその先のエージェント向けコーディング +## `code.hybscloud.com/uring` 境界周辺のエージェント向けコーディング -`code.hybscloud.com/uring` の上位またはその先にある呼び出し側コードを生成またはレビューするときは、独立したガイドの入口 [`AGENTS.md`](./AGENTS.md) を使用します。[`agents/INDEX.md`](./agents/INDEX.md) はトピック索引として使い、SQE/CQE の機構、`user_data` による識別、バッファ所有権、完了結果、ライフサイクル規則、統合境界、参照確認、そして要求分析から形式化、推論、Go へのコンパイル、検証までの流れを保ってください。 +`code.hybscloud.com/uring` 境界周辺の呼び出し側コード、つまりランタイム、プロトコルスタック、サービス、および正確な Linux `io_uring` 境界を必要とするレビュー作業を生成またはレビューするときは、独立したガイドの入口 [`AGENTS.md`](./AGENTS.md) を使用します。[`agents/INDEX.md`](./agents/INDEX.md) はトピック索引として使い、SQE/CQE の機構、`user_data` による識別、バッファ所有権、完了結果、ライフサイクル規則、統合境界、参照確認、そして要求分析から形式化、推論、Go へのコンパイル、検証までの流れを保ってください。 規則は単純です。`code.hybscloud.com/uring` はカーネルの事実を公開し、ポリシーは呼び出し側レイヤーが選びます。再試行/backoff、ポーリング周期、スケジューリング、ルーティング、ルートの終了処理、プロトコル状態、パース、完了ルーティング、キャンセルおよびタイムアウトポリシー、安全性チェック、サービスライフサイクルは `code.hybscloud.com/uring` の境界外に置き、`ErrWouldBlock`、`ErrMore`、`IORING_CQE_F_MORE`、所有権の移動、機能不足による失敗を可視のまま保ってください。 diff --git a/README.md b/README.md index 65bd138..f9717b6 100644 --- a/README.md +++ b/README.md @@ -47,9 +47,9 @@ Debian 13 ships kernel 6.12 in its stable track. The `trixie-backports` suite pr Ring creation may return `ENOMEM`, `EPERM`, or `ENOSYS` depending on memlock limits, sysctl settings, or kernel support. Container runtimes block `io_uring` syscalls by default. See [SETUP.md](./SETUP.md) for diagnosis and resolution. -## Agentic coding above or beyond `code.hybscloud.com/uring` +## Agentic coding around the `code.hybscloud.com/uring` boundary -Use the standalone guide entrypoint [`AGENTS.md`](./AGENTS.md) when generating or reviewing caller-side code above or beyond `code.hybscloud.com/uring`. Use [`agents/INDEX.md`](./agents/INDEX.md) as the topic index to preserve the kernel boundary: SQE/CQE mechanics, `user_data` identity, buffer ownership, completion outcomes, lifecycle rules, integration points, reference checks, and the workflow from analysis through formalization, reasoning, compilation into Go, and verification. +Use the standalone guide entrypoint [`AGENTS.md`](./AGENTS.md) when generating or reviewing caller-side code around the `code.hybscloud.com/uring` boundary: runtimes, protocol stacks, services, and review work that needs a precise Linux `io_uring` boundary. Use [`agents/INDEX.md`](./agents/INDEX.md) as the topic index to preserve the kernel boundary: SQE/CQE mechanics, `user_data` identity, buffer ownership, completion outcomes, lifecycle rules, integration points, reference checks, and the workflow from analysis through formalization, reasoning, compilation into Go, and verification. The rule is simple: `code.hybscloud.com/uring` exposes kernel facts; caller-side layers choose policy. Keep retry/backoff, poll cadence, scheduling, routing, route retirement, protocol state, parsing, completion routing, cancellation and timeout policy, safety checks, and service lifecycle outside the `code.hybscloud.com/uring` boundary, and keep `ErrWouldBlock`, `ErrMore`, `IORING_CQE_F_MORE`, ownership transfer, and capability failures visible. diff --git a/README.zh-CN.md b/README.zh-CN.md index 4efd8ff..2384217 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -47,9 +47,9 @@ Debian 13 稳定版默认提供的内核为 6.12，`trixie-backports` 软件源 Ring 创建可能返回 `ENOMEM`、`EPERM` 或 `ENOSYS`，分别对应 memlock 上限、sysctl 配置或内核支持等问题。容器运行时默认会阻止 `io_uring` 系统调用。诊断与解决方法见 [SETUP.md](./SETUP.md)。 -## 面向 `code.hybscloud.com/uring` 上层及其之上系统的代理编码 +## 围绕 `code.hybscloud.com/uring` 边界的代理编码 -在生成或审查位于 `code.hybscloud.com/uring` 上层及其之上系统中的调用方代码时，使用独立指南入口 [`AGENTS.md`](./AGENTS.md)。将 [`agents/INDEX.md`](./agents/INDEX.md) 作为主题索引，以保持内核边界清晰：SQE/CQE 机制、`user_data` 标识、缓冲区所有权、完成结果、生命周期规则、集成边界、参考检查，以及从需求分析、形式化、推理、编译到 Go 代码、再到验证的工作流。 +在生成或审查围绕 `code.hybscloud.com/uring` 边界的调用方代码时，包括运行时、协议栈、服务以及需要精确 Linux `io_uring` 边界的审查工作，请使用独立指南入口 [`AGENTS.md`](./AGENTS.md)。将 [`agents/INDEX.md`](./agents/INDEX.md) 作为主题索引，以保持内核边界清晰：SQE/CQE 机制、`user_data` 标识、缓冲区所有权、完成结果、生命周期规则、集成边界、参考检查，以及从需求分析、形式化、推理、编译到 Go 代码、再到验证的工作流。 规则很简单：`code.hybscloud.com/uring` 暴露内核事实；调用方层选择策略。重试/backoff、轮询节奏、调度、路由、路由退役、协议状态、解析、完成路由、取消和超时策略、安全检查和服务生命周期应留在 `code.hybscloud.com/uring` 边界之外，同时保持 `ErrWouldBlock`、`ErrMore`、`IORING_CQE_F_MORE`、所有权转移和能力检查失败可见。 diff --git a/agents/formalization/notation.md b/agents/formalization/notation.md index 6ffa3a1..851d8da 100644 --- a/agents/formalization/notation.md +++ b/agents/formalization/notation.md @@ -238,6 +238,15 @@ field access : cqe ↦ {cqe.Res, cqe.Flags, cqe.user_data} InstanceCase = { cqe, sqe, ctx, r } +CompletionInstanceCase = + { cqe, ctx, r } + +SubmissionInstanceCase = + { sqe, ctx, r } + +bound_completion_instance(x) ⇔ x ∈ CompletionInstanceCase +bound_submission_instance(x) ⇔ x ∈ SubmissionInstanceCase + SortOrKind = { CQE, SQE, Ctx, Ring, R[κ], CQEView, CQECopy, CQEFact, CQEResultResource, CQEEvent } @@ -275,7 +284,10 @@ GuideCaseInvariant ⇔ ∧ holds(path("uring/agents/workflow")) ∧ holds(path("uring/agents/runtime")) ∧ holds(path("uring/agents/lift")) - ∧ ∀x. bound_completion_instance(x) → x ∈ {cqe,ctx,r} + ∧ InstanceCase = CompletionInstanceCase ∪ SubmissionInstanceCase + ∧ ∀x. bound_completion_instance(x) → x ∈ CompletionInstanceCase + ∧ ∀x. bound_submission_instance(x) → x ∈ SubmissionInstanceCase + ∧ ∀x. bound_instance(x) → x ∈ InstanceCase ∧ ∀cqe. field_access(cqe) ⊆ {cqe.Res,cqe.Flags,cqe.user_data} ``` diff --git a/integration_linux_test.go b/integration_linux_test.go index fb3ecfa..3e26737 100644 --- a/integration_linux_test.go +++ b/integration_linux_test.go @@ -928,6 +928,7 @@ func TestQueryOpcodes(t *testing.T) { func TestRegisterFiles(t *testing.T) { ring, err := uring.New(testMinimalBufferOptions, func(opt *uring.Options) { opt.Entries = uring.EntriesSmall + opt.MultiIssuers = true // Avoid SINGLE_ISSUER io_uring_register task affinity in CI. }) if err != nil { t.Fatalf("New: %v", err) @@ -979,6 +980,7 @@ func TestRegisterFiles(t *testing.T) { func TestRegisterFilesSparse(t *testing.T) { ring, err := uring.New(testMinimalBufferOptions, func(opt *uring.Options) { opt.Entries = uring.EntriesSmall + opt.MultiIssuers = true // Avoid SINGLE_ISSUER io_uring_register task affinity in CI. }) if err != nil { t.Fatalf("New: %v", err)