@quolu/lattice 0.29.0 → 0.30.1

package/LICENSE

@@ -1,25 +1,148 @@
-MIT License
-
-Copyright (c) 2026 quolu (kitepon-rgb)
-
-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 bundled sensor (sensor/) is a fork of @colbymchenry/codegraph (MIT);
-its original license and attribution are preserved in sensor/LICENSE and
-sensor/NOTICE.
-
-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.
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+---
+
+Required Notice: Copyright 2026 quolu (kitepon-rgb) — https://github.com/kitepon-rgb/Lattice
+
+Patent notice: this software implements the subject matter of Japanese patent
+application 特願2026-178950 (filed 2026-07-27). Patent rights are reserved except as
+licensed above for permitted (noncommercial) purposes.
+
+Commercial use: not granted by these terms. A separate license from the copyright and
+patent holder is required. Enquiries: https://github.com/kitepon-rgb/Lattice/issues
+Whether such a license is granted, and on what terms, is decided case by case.
+
+Third-party components: the bundled structure sensor in `sensor/` is third-party work
+absorbed into this repository and remains under the MIT License. Its upstream origin and
+attribution are recorded in `sensor/NOTICE`; the license text is `sensor/LICENSE`.
+These terms do not modify that license.

package/README.ja.md

@@ -0,0 +1,251 @@
+<p align="center">
+  <img src=".github/og.png" alt="Lattice — 見かけだけの競合で作業を直列化しない" width="100%">
+</p>
+
+# Lattice
+
+[![npm](https://img.shields.io/npm/v/@quolu/lattice?color=cb3837&logo=npm)](https://www.npmjs.com/package/@quolu/lattice)
+[![CI](https://github.com/kitepon-rgb/Lattice/actions/workflows/ci.yml/badge.svg)](https://github.com/kitepon-rgb/Lattice/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-PolyForm%20Noncommercial%201.0.0-blue)](LICENSE)
+[![node](https://img.shields.io/node/v/@quolu/lattice?color=339933&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![patent](https://img.shields.io/badge/patent-pending%20JP%202026--178950-6366f1)](#特許)
+
+[English](README.md) · **日本語**
+
+> **見かけだけの競合で、作業を直列化しない。**
+> Latticeはmulti-agent開発のためのschedulability compilerです。codebaseの実際の境界を観測して
+> どのtaskが並列に走れるかを裏付け、本当に衝突している場合は**その境界をrefactorして
+> planを再コンパイルし、並列に走れる形へ変えます**。
+
+## なぜ要るのか
+
+3つのagentに3つのtaskを渡すと、たいてい次のどちらかで失敗します。
+
+- **直列にしすぎる。** 「どちらも`renderer.ts`を触るから順番に」——実際には*別々のsymbol*を
+  触っていて、同時に走れたかもしれない。
+- **直列にしなさすぎる。** 依存を誰も宣言しなかったので並列で走らせ、両方が書いた後で衝突に気づく。
+
+どちらも原因は同じで、**誰も境界を実測していない**ことです。task listの依存線は意図の主張であって、
+codeについての証拠ではありません。
+
+Latticeはここを違う手で塞ぎます。競合を**検出する**だけでなく**取り除く**。2つのtaskが1つのfileを
+奪い合っているなら、切り方を導出し、隔離worktreeで適用し、五条件で検証し、変換後のsourceに対して
+planを再コンパイルします。共有面が共有でなくなるので、競合辺そのものが消えます。
+
+### 実例（このrepo自身）
+
+2つの工程がどちらも`src/seam-commit.mjs`を変更する必要がありました。Latticeは宣言をcompileして
+`conflict_count: 1`・`severability: code_seam`と判定し、切り方を提案し、隔離worktreeで適用。
+五条件をすべて満たしたので、fileは工程ごとの所有面＋共有面＋残余面へ分割されました。
+再コンパイルは`conflict_count: 0`を返し、両工程は同じparallel groupに入りました。
+
+人が手で切ったのではありません。**工程を並列化するために製品が切りました。**
+
+### 変換の受入五条件
+
+**5つすべて**を満たしたときだけ採用します。1つでも欠ければ棄却です。
+
+| 条件 | 意味 |
+|---|---|
+| `behavior_equivalent` | 原pathの公開export面が保たれている |
+| `focused_tests_passed` | 影響testが変換後のsourceで実際に通る |
+| `sensor_fresh` | 構造索引を取り直し、新しい面を収載している |
+| `overlap_reduced` | 対象の競合が消え、**かつ**plan全体の競合対が増えていない |
+| `parallelism_improved` | 実行段階数が減っている |
+
+## 開発工場での位置づけ
+
+Latticeは[dotagents開発工場](https://github.com/kitepon-rgb/dotagents)が管理する
+自作コア10製品の一つです。本repoはplan／ToDo／run store、sensor、schema、migration、
+release、diagnosticsを所有し、dotagentsは製品横断の工程利用・導入・host統合を所有します。
+廃止済みの前身sensorは独立製品として配線せず、Lattice sensorだけを現役面とします。
+MarkItDownは別区分の第三者CLIです。
+
+現在の工程状態と完了証拠の正本は、このrepoのLattice storeです。文書の役割と現行導線は
+[docs/README.md](docs/README.md)、製品思想は[PLAN.md](PLAN.md)、公開contractは
+[docs/00_product-contract.md](docs/00_product-contract.md)を参照してください。
+
+CLIの全体像は`lattice --help`、各公開namespaceの正規構文は
+`lattice <plan|run|event|todo|sensor|factory-diagnostics|runtime-errors|bridge> --help`で確認できます。
+個別操作は`lattice <namespace> <subcommand> --help`または`lattice help <namespace> <subcommand>`で
+正規optionをstore非依存に確認できます。
+
+## 開発
+
+```bash
+npm test
+npm run check
+npm run ci
+node scripts/reap-orphan-test-daemons.mjs
+lattice sensor sync . --json
+spotter doctor
+codex-sidecar diagnostics --project . --preset auditor --json
+```
+
+`reap-orphan-test-daemons.mjs`は、実daemonを起動するtestが取り残したprocessを一覧します。既定は表示
+だけで何も停めません。停めるのは`--reap`を付けた時に限り、対象はargvが指すfixtureのdirectoryが既に
+存在しないものだけです。実行中のtestを巻き込まないための条件なので、fixtureが残ったまま死んだ実行を
+含めたい場合だけ`--older-than-hours=<n>`で起動時刻による許可を明示します。
+
+未初期化projectで`sensor sync`した場合は`LATTICE_SENSOR_NOT_INITIALIZED`と正規`next_action`を返します。
+その他のsensor失敗もexit code、signal、bounded stderrをtyped detailへ残し、原因を隠しません。
+
+Node.js 22.13以上を使用します。境界観測は配布物に同梱したLattice sensorだけを使い、PATH上の
+廃止済みruntimeや旧cache/dataへfallbackしません。Spotterはproject単位で生成stateの所有境界を守ります。
+
+どのrepoでも、Latticeの導入状態はdirectoryの有無を推測せず、最初に次のtyped discoveryで判定します。
+
+```bash
+lattice status --json
+```
+
+`state`は`uninitialized | ready | active_run | invalid`のいずれかです。`uninitialized`は
+正常な未初期化状態で、`next_action`が正規の初期authoring入口を返します。初回planは
+新規planはPhase監査とToDo schedulingを分離する`lattice.plan_create_input.v3`のcanonical
+JSON+LFを用意し、次で作成します。既存v2/v4は互換契約として維持されます。
+
+```bash
+lattice plan create --schema-version 3 --json
+```
+
+```bash
+lattice plan create --input .lattice/plan-create.json
+```
+
+`invalid`をMarkdown fallbackへ丸めず、`next_action`に従ってstoreを診断してください。
+discoveryと初期transactionの不変条件は
+[ADR 0058](docs/adr/0058-project-discovery-and-initial-authoring.md)が正です。
+
+## 実行runを端から端まで動かす
+
+compileしたrunを実際にdispatchするには、executor adapterを登録してからactivateします。
+参照実装の`lattice-scripted-adapter`を配布しているため、公開CLIと配布binだけで
+実write・receipt受理・closeまで到達できます。
+
+```bash
+lattice run adapter register --schema --json     # 登録入力のJSON Schema
+lattice run adapter register --input adapter.json
+lattice run adapter list --json
+lattice run activate --run .lattice/runs/<id>
+lattice run status --run .lattice/runs/<id>      # accepted に子が入る
+lattice event verify --run .lattice/runs/<id>
+lattice run close --run .lattice/runs/<id>
+```
+
+digestは手で計算しません。binary・config・capabilities・自己digestは登録時にCLIが導出します。
+
+`plan compile`が`BOUNDARY_UNKNOWN`を返す場合は、まず`git status --short`が空かを確認してください。
+未追跡ファイルがあるとsensor statusが`stale`になり、witnessが未解決unknownへ落ちます。
+作業ツリーをcleanにすると同じrequestがそのまま通ります。
+
+TODO工程storeの読取は`lattice todo status`、`compile_binding`付きTaskの投影は
+`lattice todo bindings`、検証は`lattice todo verify`、表示生成は
+`lattice todo gantt`を使います。topology/source reconciliationは
+`lattice todo revise --plan <key> --input <canonical-revision.json>`、Phase付きplanは
+`lattice todo revise-phase --plan <key> --input <canonical-phase-revision.json>`でsuccessor発行します。
+cross-plan topologyを同時に切り替える場合は
+`lattice todo revise-set --input <canonical-revision-set.json>`を使い、Phase revisionを含む集合は
+`lattice.todo_revision_set.v3`で通常revisionと混在できます。
+Phase付きv5 planでは、通常ToDoの開始順はToDo DAGだけで決まり、Phase前後関係は重監査の順序だけを
+制御します。特定ToDoがPhase受理を本当に必要とする場合だけ`phase_accept_dependencies`で明示します。
+`lattice todo status --json`の`dispatch_frontier`はready全件を同時dispatchする既定を示します。
+readyが複数なら最初のstartに`--parallel-frontier`を付け、subsetだけを直列着手する場合は
+`--override-reason <reason>`で理由を残します。
+
+```bash
+lattice todo start --plan <key> --task <id> --parallel-frontier
+lattice todo start --plan <key> --task <id> --override-reason <reason>
+```
+
+`--parallel-frontier`はhostへ並列dispatch方針を宣言する開始gateです。Lattice自身がAI hostのagentを
+起動するものではなく、実際のdispatchはhostが行います。宣言後もready全件が着手されたかは
+`active_set`と`next_ready`で観測できます。
+ToDo完了は軽量確認までで、所属ToDoが全てdoneになったPhaseは`gate_ready`となり、`todo phase review`後に
+required evidenceを束縛した`todo phase accept`で重監査の判断を記録します。監査回数やPhase数を自動追加する
+機能ではありません。Phase状態は
+`lattice todo phase status --plan <key>`、閲覧中に進捗が更新される工程表は
+`lattice todo gantt serve --port 0`で確認できます。live viewerはloopback-only、read-onlyで、
+`/projects/<project_id>/`というproject固有URLを返します。別projectからそれぞれ起動すれば、独立port・独立SSE経路で同時表示できます。
+session開始時のtyped discoveryで使う`lattice status --json`と、actor環境変数を持つ通常のTODO操作は
+active projectを自動登録し、一つのloopback dashboard daemonを再利用します。
+`/projects/`の一覧からproject固有の工程図を開け、各projectのSSE更新は互いに分離されます。
+dashboardはmanifestのfile identityが変わらない間のstable store readを再利用します。
+巨大工程図のrender中にhealth応答が遅れても、生存中dashboardを新daemonで置き換えず
+`DASHBOARD_DAEMON_UNRESPONSIVE`としてtyped拒否します。
+最近のsession activityが期限切れでも、Lattice storeの`active_set`が非空なprojectは一覧へ残ります。
+長時間の外部処理中にCLI呼出しが途切れても進行中projectを休眠扱いしません。
+LANや外部reverse proxyから閲覧するoptional bridgeは既定で無効です。明示したIPにだけbindする初回設定、
+再設定、停止方法は[bridge setup](docs/bridge-setup.md)を参照してください。reverse proxy hostへsshで
+到達できる場合は、LANへbindせずloopbackだけを逆トンネルで公開する構成も選べます。
+工程図の既定表示は、後続に作業中・未着手が残っていない完了工程を図から除きます。まとめnodeも置かないため、
+完走したplanは図の場所を取りません。除いた工程は凡例の件数、右ペインの「全工程」一覧、各工程の詳細から
+辿れ、詳細の前提・後続は除外前の依存関係を示します。総数・進捗・最長依存鎖は除外前の全工程で数えます。
+凡例の件数バッジを押すと全工程を描いた図へ切り替わり、`lattice todo gantt --scope all`は最初から全件を
+描きます。表示規約は[ADR 0066](docs/adr/0066-gantt-live-scope-drops-finished-work.md)が正です。
+
+右ペインは概要・選択工程・全工程の3面で、いずれもToDo storeを表示します（元plan Markdown本文は
+再表示しません。元文書へは各工程の詳細が持つ行対応から辿ります）。全工程一覧は動いているplanを
+最終活動の新しい順で上に、全工程が図から外れた完走planを古い順で下にまとめ、plan内は登録順です。
+決着済みPhaseと図から外した工程は既定で畳み、開けば読めます。規約は
+[ADR 0067](docs/adr/0067-right-pane-shows-the-store-and-orders-by-activity.md)が正です。
+
+静的工程表は`lattice todo gantt status`で`current / stale / missing`を確認でき、HTMLまたは
+digest付きsidecarの欠落・改ざんはtyped failureになります。
+dashboard daemonは起動時に読み込んだ版数をhealthで名乗り、installされた版と食い違えば`lattice status`の
+たびに新版daemonへ置き換わります。publishしただけで配信面が古いまま残ることはありません。
+入れ替えは新daemonが登録済み全projectのstoreを読み終えるまで待つため、`lattice status`の応答が
+その間伸びます（実測: 8 project登録で約50秒台）。待ち時間は固定秒数ではなく、spawnした子が生きている
+間だけ待ち、子が死ねば即座に`DASHBOARD_DAEMON_UNAVAILABLE`を返します。既定120秒の上限は、応答を
+返さない子に対するbackstopであって正常な起動時間の見積りではありません。
+状態を書き込む`start / block / unblock / done / evidence promote / reopen / revise / revise-phase / revise-set`
+では、監査actorとして次の3環境変数をすべて設定してください。
+
+```bash
+export LATTICE_TODO_ACTOR_HOST=<host-id>
+export LATTICE_TODO_ACTOR_SESSION=<session-id>
+export LATTICE_TODO_ACTOR_AGENT=<agent-id>
+```
+
+不足またはidentifierとして不正な値がある場合、mutationはstoreを変更せず`ACTOR_UNRESOLVED`を返します。
+error detailの`missing_environment`／`invalid_environment`と
+`next_action: set_required_actor_environment_and_retry`を確認し、正規値を設定して同じ操作を再試行してください。
+
+正確なargv、evidence descriptor、result wireは
+[ADR 0056](docs/adr/0056-todo-authoring-transitions.md)を参照してください。
+
+## 特許
+
+本repositoryの設計は日本国特許出願の対象です。
+
+| | |
+|---|---|
+| 出願番号 | 特願2026-178950 |
+| 出願日 | 2026-07-27 |
+| 発明の名称 | 情報処理装置、ソフトウェア開発制御方法及びプログラム |
+| 請求項 | 12項 |
+
+**特許権は留保します。** 非商用利用についてはsoftwareと一緒に許諾します（下記License参照）。
+**商用利用は許諾しません**——著作権のlicenseも特許のlicenseも商用へは及びません。
+出願を明記するのは、権利の所在を後から知るのでなく最初に見えるようにするためです。
+
+## License
+
+**[PolyForm Noncommercial License 1.0.0](LICENSE)** — 非商用利用は無償です。
+
+- **無償:** 個人のproject、学習・研究、趣味やアマチュアの制作、慈善団体、教育機関、
+  公的研究機関、政府機関
+- **許諾しません:** 商用利用。Lattice自体を再配布するかどうかに関わらず、企業の業務や製品の
+  中で使う場合を含みます
+
+これはOSI承認のオープンソースライセンス**ではありません**。設計が特許出願の対象であり、
+商用の権利を留保しているので、意図してそうしています。
+
+**商用利用には**、著作権者・特許権者からの別途の許諾が必要です。
+問い合わせは[issue](https://github.com/kitepon-rgb/Lattice/issues)から受け付けます。
+許諾するかどうか、どのような条件にするかは個別に判断します。
+
+同梱の構造sensor（[`sensor/`](sensor/)）は本repositoryへ吸収した第三者成果物で、
+**MIT License**のままです。upstreamの出自と帰属表示は[`sensor/NOTICE`](sensor/NOTICE)、
+license本文は[`sensor/LICENSE`](sensor/LICENSE)が持ちます。上記の条件はこれを変更しません。
+
+© 2026 quolu (kitepon-rgb)