create-windy 0.8.3 → 0.10.0

package/template/apps/agent-server/documents/query_report.py

@@ -0,0 +1,136 @@
+"""Build a source-attributed DOCX from a complete, normalized MCP query export.
+
+This checks a local export's declared coverage, not its authenticity or authorization.
+The MCP caller must fetch/re-authorize every page and normalize the actual tool response.
+"""
+
+import argparse
+import json
+from datetime import datetime
+from decimal import Decimal
+from hashlib import sha256
+from pathlib import Path
+
+from office import MAX_ROWS, check_input, money, new_document, save_new
+
+
+def required_text(value, field: str, limit: int = 2048) -> str:
+    if not isinstance(value, str) or not value.strip() or len(value) > limit:
+        raise ValueError(f"invalid {field}")
+    return value
+
+
+def validate_snapshot(snapshot: dict) -> tuple[dict, list[dict], Decimal]:
+    if (not isinstance(snapshot, dict) or type(snapshot.get("schemaVersion")) is not int
+            or snapshot["schemaVersion"] != 1):
+        raise ValueError("unsupported snapshot schema")
+    if snapshot.get("complete") is not True or snapshot.get("errors") != []:
+        raise ValueError("incomplete or partially failed query export")
+    if snapshot.get("partial", False) is not False or snapshot.get("truncated", False) is not False:
+        raise ValueError("query export declares partial or truncated coverage")
+    source = snapshot.get("source")
+    if not isinstance(source, dict) or source.get("kind") not in (
+        "synthetic-fixture", "mcp-query-export"
+    ):
+        raise ValueError("missing explicit source kind")
+    for key in ("tool", "queryId", "scope", "query", "capturedAt"):
+        required_text(source.get(key), f"source.{key}")
+    required_text(source.get("unit"), "source.unit", limit=32)
+    if "metric" in source:
+        required_text(source["metric"], "source.metric", limit=64)
+    captured_at = datetime.fromisoformat(source["capturedAt"].replace("Z", "+00:00"))
+    if captured_at.tzinfo is None:
+        raise ValueError("capturedAt must include timezone")
+    total = snapshot.get("total")
+    if type(total) is not int or not 0 <= total <= MAX_ROWS:
+        raise ValueError("missing total or total exceeds row budget")
+    pages = snapshot.get("pages")
+    if not isinstance(pages, list) or not 1 <= len(pages) <= 100:
+        raise ValueError("missing pages or page budget exceeded")
+    records, identifiers, visited = [], set(), set()
+    expected_cursor, amount = None, Decimal("0.00")
+    for index, page in enumerate(pages):
+        if not isinstance(page, dict) or page.get("status") != "success":
+            raise ValueError("query page failed")
+        if page.get("truncated") is not False or page.get("partial", False) is not False:
+            raise ValueError("truncated or partial query page")
+        if page.get("errors", []) != []:
+            raise ValueError("query page contains errors")
+        if "cursor" not in page or "nextCursor" not in page:
+            raise ValueError("pagination cursors must be explicit")
+        cursor, following = page["cursor"], page["nextCursor"]
+        if cursor != expected_cursor:
+            raise ValueError("missing or out-of-order query page")
+        if following is not None:
+            required_text(following, "nextCursor")
+            if following in visited:
+                raise ValueError("repeated pagination cursor")
+            visited.add(following)
+        if (index == len(pages) - 1) != (following is None):
+            raise ValueError("pagination must terminate exactly on the final page")
+        expected_cursor = following
+        items = page.get("records")
+        if not isinstance(items, list) or len(records) + len(items) > MAX_ROWS:
+            raise ValueError("invalid records or row budget exceeded")
+        for item in items:
+            if not isinstance(item, dict):
+                raise ValueError("invalid record")
+            identifier = required_text(item.get("id"), "record.id")
+            required_text(item.get("label"), "record.label")
+            required_text(item.get("sourceRef"), "record.sourceRef")
+            if "unit" in item and item["unit"] != source["unit"]:
+                raise ValueError("mixed record units require explicit normalization before reporting")
+            if identifier in identifiers:
+                raise ValueError("duplicate record across query pages")
+            identifiers.add(identifier)
+            # Exporters must preserve decimal strings, rather than JSON floating point.
+            required_text(item.get("amount"), "record.amount", limit=32)
+            amount += money(item["amount"])
+            records.append(item)
+    if len(records) != total:
+        raise ValueError("record count differs from declared total")
+    return source, records, amount
+
+
+def generate_report(source_path: Path, output: Path) -> dict:
+    if output.suffix.lower() != ".docx":
+        raise ValueError("report output must use .docx")
+    check_input(source_path)
+    payload = source_path.read_bytes()
+    source_digest = sha256(payload).hexdigest()
+    snapshot = json.loads(payload)
+    source, records, total = validate_snapshot(snapshot)
+    metric = source.get("metric", "金额")
+    document = new_document("查询数据汇总报告")
+    if source["kind"] == "synthetic-fixture":
+        document.add_paragraph("脱敏合成样例，仅用于文件和来源覆盖检查。")
+    document.add_paragraph(f"导出时声明的查询范围：{source['scope']}")
+    document.add_paragraph(f"查询条件：{source['query']}")
+    document.add_paragraph(f"在该范围内完成 {len(snapshot['pages'])} 页，共 {len(records)} 条记录。")
+    document.add_paragraph(f"{metric}合计：{format(total, '.2f')} {source['unit']}（Decimal 计算）。")
+    table = document.add_table(rows=1, cols=4)
+    table.style = "Light Shading Accent 1"
+    for cell, label in zip(table.rows[0].cells, ("记录 ID", "名称", f"{metric}（{source['unit']}）", "来源定位")):
+        cell.text = label
+    for record in records:
+        values = (record["id"], record["label"], format(money(record["amount"]), ".2f"),
+                  record["sourceRef"])
+        for cell, value in zip(table.add_row().cells, values):
+            cell.text = value
+    document.add_heading("来源与覆盖边界", level=1)
+    for label, value in (("MCP 工具", source["tool"]), ("查询关联", source["queryId"]),
+                         ("导出时间", source["capturedAt"]), ("快照 SHA256", source_digest)):
+        document.add_paragraph(f"{label}：{value}")
+    document.add_paragraph("来源定位用于回查；访问来源仍按当前身份和数据范围重新授权。")
+    document.add_paragraph("报告反映该导出时点和筛选范围，不代表其他范围或实时数据库全量。")
+    save_new(document, output)
+    return {"records": len(records), "total": format(total, ".2f"), "unit": source["unit"], "metric": metric,
+            "sourceSha256": source_digest, "sourceKind": source["kind"]}
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("snapshot", type=Path)
+    parser.add_argument("output", type=Path)
+    arguments = parser.parse_args()
+    print(json.dumps(generate_report(arguments.snapshot, arguments.output), ensure_ascii=False))

package/template/apps/agent-server/documents/smoke.py

@@ -0,0 +1,177 @@
+"""Synthetic local file round-trips, not a DSH/model/customer acceptance test."""
+
+import argparse
+import copy
+import json
+import platform
+from datetime import datetime
+from decimal import Decimal
+from importlib.metadata import version
+from pathlib import Path
+from tempfile import mkdtemp
+
+from docx import Document
+from openpyxl import Workbook, load_workbook
+from openpyxl.xml import DEFUSEDXML
+from reportlab.pdfbase import pdfmetrics
+from reportlab.pdfbase.cidfonts import UnicodeCIDFont
+from reportlab.pdfgen.canvas import Canvas
+
+from office import digest, read_text, save_new, summarize_excel, write_revision
+from query_report import generate_report, validate_snapshot
+
+
+def require(condition: bool, message: str) -> None:
+    if not condition:
+        raise AssertionError(message)
+
+
+def rejects(action, message: str) -> None:
+    try:
+        action()
+    except (ValueError, FileExistsError):
+        return
+    raise AssertionError(message)
+
+
+def fixture_snapshot() -> dict:
+    return {
+        "schemaVersion": 1,
+        "source": {"kind": "synthetic-fixture", "tool": "fixture.query",
+                   "queryId": "synthetic-query-001", "capturedAt": "2026-10-15T08:00:00Z",
+                   "scope": "合成案件 SYNTHETIC-001", "unit": "元", "query": "合成记录，金额单位为元"},
+        "complete": True, "errors": [], "total": 3,
+        "pages": [
+            {"cursor": None, "nextCursor": "page-2", "status": "success", "truncated": False,
+             "records": [{"id": "001", "label": "样例甲", "amount": "10.10",
+                          "sourceRef": "fixture://SYNTHETIC-001/001"},
+                         {"id": "002", "label": "样例乙", "amount": "20.20",
+                          "sourceRef": "fixture://SYNTHETIC-001/002"}]},
+            {"cursor": "page-2", "nextCursor": None, "status": "success", "truncated": False,
+             "records": [{"id": "003", "label": "样例丙", "amount": "0.03",
+                          "sourceRef": "fixture://SYNTHETIC-001/003"}]},
+        ],
+    }
+
+
+def document_checks(directory: Path) -> dict:
+    original = directory / "original.docx"
+    document = Document()
+    document.add_heading("合成材料", 0)
+    document.add_paragraph("初稿：甲事项尚待整理。")
+    save_new(document, original)
+    source_hash = digest(original)
+    revision, continued = directory / "revision-1.docx", directory / "revision-2.docx"
+    write_revision(original, revision, read_text(original).replace("尚待整理", "已完成整理"), "修订稿")
+    write_revision(revision, continued, read_text(revision) + "\n续改：补充核对记录。", "续改稿")
+    require("已完成整理" in read_text(continued) and "补充核对记录" in read_text(continued),
+            "DOCX continuation did not round-trip")
+    require(digest(original) == source_hash, "original DOCX was modified")
+    rejects(lambda: write_revision(original, original, "覆盖", "覆盖"), "original overwrite accepted")
+    rejects(lambda: write_revision(original, revision, "覆盖", "覆盖"), "revision overwrite accepted")
+    pdf = directory / "original.pdf"
+    pdfmetrics.registerFont(UnicodeCIDFont("STSong-Light"))
+    canvas = Canvas(str(pdf), invariant=1)
+    canvas.setFont("STSong-Light", 12)
+    canvas.drawString(72, 750, "合成 PDF：金额 30.33 元。")
+    canvas.save()
+    pdf_hash = digest(pdf)
+    extracted = read_text(pdf)
+    require("30.33" in extracted and "合成" in extracted, "PDF text extraction failed")
+    pdf_revision = directory / "pdf-revision.docx"
+    write_revision(pdf, pdf_revision, extracted + "\n已核对金额与来源。", "PDF 改写稿")
+    require("已核对金额" in read_text(pdf_revision), "PDF-to-DOCX read-back failed")
+    require(digest(pdf) == pdf_hash, "original PDF was modified")
+    return {"docxContinuation": "passed", "pdfTextToDocx": "passed",
+            "sourcePreservation": "passed", "existingOutputRefusal": "passed"}
+
+
+def excel_checks(directory: Path) -> dict:
+    original, result = directory / "original.xlsx", directory / "summary.xlsx"
+    workbook = Workbook()
+    sheet = workbook.active
+    sheet.append(["编号", "名称", "日期", "金额"])
+    for identifier, label, amount in (("000001", "样例甲", "10.10"),
+                                      ("000002", "样例乙", "20.20"),
+                                      ("000003", "样例丙", "0.03")):
+        sheet.append([identifier, label, datetime(2026, 10, 15), amount])
+        sheet.cell(sheet.max_row, 1).number_format = "@"
+        sheet.cell(sheet.max_row, 3).number_format = "yyyy-mm-dd"
+    save_new(workbook, original)
+    original_hash = digest(original)
+    require(summarize_excel(original, result, unit="元") == Decimal("30.33"), "decimal total mismatch")
+    check = load_workbook(result, read_only=True, data_only=True)
+    try:
+        rows = list(check.active.values)
+        require(rows[1][0] == "000001" and rows[1][1] == "样例甲", "Chinese/leading zeros lost")
+        require(rows[1][2] == datetime(2026, 10, 15), "Excel date lost")
+        require(rows[-1][3] == "30.33", "decimal summary did not round-trip exactly")
+    finally:
+        check.close()
+    require(digest(original) == original_hash, "original Excel was modified")
+    sheet["D2"] = "=1+2"
+    formula = directory / "formula.xlsx"
+    save_new(workbook, formula)
+    rejects(lambda: summarize_excel(formula, directory / "formula-result.xlsx", unit="元"),
+            "unverified formula engine accepted")
+    return {"chineseDateLeadingZeros": "passed", "decimalTotal": "30.33",
+            "formulaRefusal": "passed"}
+
+
+def query_checks(directory: Path) -> dict:
+    snapshot = fixture_snapshot()
+    source, output = directory / "query-snapshot.json", directory / "query-report.docx"
+    source.write_text(json.dumps(snapshot, ensure_ascii=False, indent=2), encoding="utf-8")
+    result = generate_report(source, output)
+    text = read_text(output)
+    require(result["records"] == 3 and result["total"] == "30.33", "query totals differ")
+    require(digest(source) in text and "fixture://SYNTHETIC-001/003" in text,
+            "report source attribution missing")
+    require("金额合计：30.33 元" in text, "source unit was not preserved")
+    invalid = []
+    for field, value in (("complete", False), ("errors", ["failed page"]), ("total", 4)):
+        candidate = copy.deepcopy(snapshot)
+        candidate[field] = value
+        invalid.append(candidate)
+    for field, value in (("truncated", True), ("status", "failed"),
+                         ("cursor", "missing-page"), ("nextCursor", "not-finished")):
+        candidate = copy.deepcopy(snapshot)
+        candidate["pages"][-1][field] = value
+        invalid.append(candidate)
+    duplicate = copy.deepcopy(snapshot)
+    duplicate["pages"][-1]["records"][0]["id"] = "001"
+    invalid.append(duplicate)
+    missing_unit = copy.deepcopy(snapshot)
+    del missing_unit["source"]["unit"]
+    invalid.append(missing_unit)
+    for candidate in invalid:
+        rejects(lambda: validate_snapshot(candidate), "incomplete/invalid query export accepted")
+    return {"sourceCoverage": "passed", "invalidSnapshotsRejected": len(invalid), **result}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output-dir", type=Path,
+                        help="must be new; defaults to an isolated directory under /tmp")
+    arguments = parser.parse_args()
+    directory = arguments.output_dir or Path(mkdtemp(prefix="dsh-documents-"))
+    if arguments.output_dir:
+        directory.mkdir(parents=True, exist_ok=False)
+    require(DEFUSEDXML, "openpyxl must use installed defusedxml protection")
+    checks = {"documents": document_checks(directory), "excel": excel_checks(directory),
+              "queryReport": query_checks(directory)}
+    evidence = {"validation": "synthetic-library-round-trip", "outputDirectory": str(directory),
+                "runtime": {"python": platform.python_version(), "platform": platform.platform(),
+                            "packages": {name: version(name) for name in (
+                                "python-docx", "openpyxl", "pypdf", "reportlab", "defusedxml",
+                                "lxml", "typing-extensions", "et-xmlfile", "pillow", "charset-normalizer")}},
+                "checks": checks, "visualQuality": "not-verified", "realModel": "not-invoked",
+                "liveMcpAuthorization": "not-verified", "automaticBusinessArchive": False,
+                "files": {file.name: digest(file) for file in directory.iterdir() if file.is_file()}}
+    (directory / "evidence.json").write_text(json.dumps(evidence, ensure_ascii=False, indent=2),
+                                              encoding="utf-8")
+    print(json.dumps(evidence, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/template/apps/agent-server/documents/test_boundaries.py

@@ -0,0 +1,185 @@
+"""Focused document regressions; no model, server, browser, or live MCP is involved."""
+
+import copy
+import json
+import re
+import tempfile
+import unittest
+from datetime import datetime
+from decimal import Decimal
+from pathlib import Path
+from zipfile import ZipFile
+
+from docx import Document
+from openpyxl import Workbook, load_workbook
+from reportlab.pdfgen.canvas import Canvas
+
+from office import digest, read_text, save_new, summarize_excel, write_revision
+from query_report import generate_report, validate_snapshot
+from smoke import fixture_snapshot
+
+
+class DocumentBoundaries(unittest.TestCase):
+    def setUp(self):
+        self.temporary = tempfile.TemporaryDirectory(prefix="dsh-document-boundaries-")
+        self.directory = Path(self.temporary.name)
+
+    def tearDown(self):
+        self.temporary.cleanup()
+
+    def workbook(self, path: Path, *, literal: bool = False, formula: bool = False):
+        workbook = Workbook()
+        sheet = workbook.active
+        sheet.title = "来源数据"
+        sheet.append(["编号", "名称", "日期", "金额"])
+        sheet.append(["000001", '=HYPERLINK("https://example.invalid/","样例")',
+                      datetime(2026, 10, 16), "10.10"])
+        sheet["B2"].data_type = "s" if literal else "f"
+        if not literal and not formula:
+            sheet["B2"] = "普通样例"
+        sheet.append(["000002", "第二行", datetime(2026, 10, 16), "20.20"])
+        save_new(workbook, path)
+
+    def test_literal_equals_text_stays_text_with_source_and_unit(self):
+        source, output = self.directory / "source.xlsx", self.directory / "summary.xlsx"
+        self.workbook(source, literal=True)
+        before = digest(source)
+        self.assertEqual(summarize_excel(source, output, unit="万元"), Decimal("30.30"))
+        workbook = load_workbook(output, data_only=False)
+        try:
+            self.assertEqual(workbook.active["B2"].data_type, "s")
+            self.assertEqual(workbook.active["B2"].value,
+                             '=HYPERLINK("https://example.invalid/","样例")')
+            self.assertEqual(workbook.active["A2"].value, "000001")
+            self.assertIn("万元", workbook.active["D1"].comment.text)
+            provenance = dict(workbook["来源说明"].values)
+            self.assertEqual(provenance["金额单位"], "万元")
+            self.assertEqual(provenance["单位转换"], "未转换")
+            self.assertEqual(provenance["来源 SHA256"], before)
+            self.assertEqual(provenance["来源范围"], "来源数据!A1:D3")
+            self.assertEqual(provenance["Decimal 合计"], "30.30")
+        finally:
+            workbook.close()
+        self.assertEqual(digest(source), before)
+
+    def test_real_formula_and_missing_unit_are_rejected_without_output(self):
+        source, output = self.directory / "formula.xlsx", self.directory / "rejected.xlsx"
+        self.workbook(source, formula=True)
+        with self.assertRaisesRegex(ValueError, "formula"):
+            summarize_excel(source, output, unit="元")
+        self.assertFalse(output.exists())
+        with self.assertRaisesRegex(ValueError, "unit"):
+            summarize_excel(source, output, unit="")
+        self.assertFalse(output.exists())
+
+    def test_false_xlsx_dimensions_do_not_silently_drop_rows(self):
+        source = self.directory / "source.xlsx"
+        self.workbook(source)
+        forged = self.directory / "understated-dimensions.xlsx"
+        with ZipFile(source) as original, ZipFile(forged, "w") as target:
+            for entry in original.infolist():
+                content = original.read(entry.filename)
+                if entry.filename == "xl/worksheets/sheet1.xml":
+                    content = re.sub(rb'<dimension ref="[^"]+"', b'<dimension ref="A1:D1"', content)
+                target.writestr(entry, content)
+        output = self.directory / "complete-summary.xlsx"
+        self.assertEqual(summarize_excel(forged, output, unit="元"), Decimal("30.30"))
+        workbook = load_workbook(output, read_only=True)
+        try:
+            self.assertEqual(workbook.active["A3"].value, "000002")
+            self.assertEqual(dict(workbook["来源说明"].values)["数据行数"], "2")
+        finally:
+            workbook.close()
+
+    def test_excel_error_cell_is_rejected_but_literal_error_name_is_kept(self):
+        source = self.directory / "error.xlsx"
+        self.workbook(source)
+        workbook = load_workbook(source)
+        try:
+            workbook.active["B2"] = "#REF!"
+            error_file = self.directory / "actual-error.xlsx"
+            save_new(workbook, error_file)
+            with self.assertRaisesRegex(ValueError, "error cells"):
+                summarize_excel(error_file, self.directory / "rejected-error.xlsx", unit="元")
+            workbook.active["B2"].data_type = "s"
+            literal_file = self.directory / "literal-error.xlsx"
+            save_new(workbook, literal_file)
+        finally:
+            workbook.close()
+        output = self.directory / "literal-error-result.xlsx"
+        summarize_excel(literal_file, output, unit="元")
+        result = load_workbook(output, data_only=False)
+        try:
+            self.assertEqual((result.active["B2"].value, result.active["B2"].data_type), ("#REF!", "s"))
+        finally:
+            result.close()
+
+    def test_docx_body_table_order_and_original_revision_are_preserved(self):
+        source = self.directory / "source.docx"
+        document = Document()
+        document.add_paragraph("正文前段")
+        document.add_table(rows=1, cols=1).cell(0, 0).text = "表格中段"
+        document.add_paragraph("正文后段")
+        save_new(document, source)
+        text = read_text(source)
+        self.assertLess(text.index("正文前段"), text.index("表格中段"))
+        self.assertLess(text.index("表格中段"), text.index("正文后段"))
+        before = digest(source)
+        revision, continued = self.directory / "v1.docx", self.directory / "v2.docx"
+        write_revision(source, revision, text + "\n首轮修改", "首轮")
+        revision_before = digest(revision)
+        write_revision(revision, continued, read_text(revision) + "\n续改", "续改")
+        with self.assertRaises(FileExistsError):
+            write_revision(source, revision, "不得覆盖", "错误覆盖")
+        self.assertEqual(digest(source), before)
+        self.assertEqual(digest(revision), revision_before)
+        self.assertIn(revision_before, Document(continued).core_properties.subject)
+
+    def test_pdf_page_without_text_cannot_be_claimed_as_complete_read(self):
+        source = self.directory / "mixed-pages.pdf"
+        canvas = Canvas(str(source))
+        canvas.drawString(72, 720, "Readable first page")
+        canvas.showPage()
+        canvas.rect(72, 600, 200, 100)
+        canvas.showPage()
+        canvas.save()
+        with self.assertRaisesRegex(ValueError, "without extractable text"):
+            read_text(source)
+
+    def test_query_coverage_and_mixed_units_fail_before_output(self):
+        for mutation in ("partial", "truncated", "mixed-unit"):
+            snapshot = copy.deepcopy(fixture_snapshot())
+            if mutation == "mixed-unit":
+                snapshot["pages"][0]["records"][0]["unit"] = "万元"
+            else:
+                snapshot[mutation] = True
+            source = self.directory / f"{mutation}.json"
+            source.write_text(json.dumps(snapshot), encoding="utf-8")
+            output = self.directory / f"{mutation}.docx"
+            with self.subTest(mutation=mutation), self.assertRaises(ValueError):
+                generate_report(source, output)
+            self.assertFalse(output.exists())
+
+    def test_declared_unit_is_kept_without_conversion(self):
+        snapshot = fixture_snapshot()
+        snapshot["source"]["unit"] = "万元"
+        snapshot["pages"][0]["records"][0]["unit"] = "万元"
+        self.assertEqual(validate_snapshot(snapshot)[2], Decimal("30.33"))
+        source, output = self.directory / "wan.json", self.directory / "wan.docx"
+        source.write_text(json.dumps(snapshot), encoding="utf-8")
+        self.assertEqual(generate_report(source, output)["unit"], "万元")
+        self.assertIn("金额合计：30.33 万元", read_text(output))
+
+    def test_oversized_output_is_rejected_before_file_is_created(self):
+        class OversizedDocument:
+            def save(self, stream):
+                stream.write(b"x" * (20 * 1024 * 1024 + 1))
+
+        output = self.directory / "too-large.docx"
+        with self.assertRaisesRegex(ValueError, "download budget"):
+            save_new(OversizedDocument(), output)
+        self.assertFalse(output.exists())
+
+
+if __name__ == "__main__":
+    unittest.main()

package/template/apps/agent-server/host-contracts.ts

@@ -0,0 +1,56 @@
+/** Deployment-owned extension points. Secrets and authorization remain in the Host. */
+export interface DshHostConfiguration {
+  /** Stable deployment preset identity; retain it when adopting existing sessions. */
+  readonly presetId?: string;
+  readonly assistantName: string;
+  readonly assistantDescription: string;
+  readonly workspaceLabel: string;
+  readonly instructions: readonly string[];
+  /** Read-only, deployment-owned skill roots relative to the Agent Server. */
+  readonly skillDirectories: readonly string[];
+  /** Additional trusted Host plugins; use public DSH services and lifecycle effects. */
+  readonly plugins: readonly {
+    readonly key: string;
+    readonly path: string;
+    readonly config?: Readonly<Record<string, unknown>>;
+    readonly replaces?: readonly "session-controller"[];
+  }[];
+  /** Fixed project endpoints behind the current worker identity. */
+  readonly boundaryRoutes?: readonly DshBoundaryRoute[];
+}
+
+export interface DshBoundaryRequest {
+  readonly method: "GET" | "POST";
+  readonly path: string;
+  readonly parameters: Readonly<Record<string, string>>;
+  readonly searchParams: URLSearchParams;
+  readonly body: Uint8Array;
+  readonly signal: AbortSignal;
+}
+
+export interface DshProductRequest {
+  readonly method?: "GET" | "POST";
+  readonly body?: string | Uint8Array;
+  readonly contentType?: "application/json" | "application/octet-stream";
+}
+
+export interface DshBoundaryContext {
+  readonly actorId: string;
+  readonly signal: AbortSignal;
+  /** Fixed product origin, current login, no caller-selected credentials or redirects. */
+  fetchProduct(path: string, input?: DshProductRequest): Promise<Response>;
+}
+
+export interface DshBoundaryRoute {
+  readonly key: string;
+  readonly method: "GET" | "POST";
+  /** Literal path segments and optional :identifier parameters; no wildcards. */
+  readonly path: string;
+  readonly maxBodyBytes?: number;
+  readonly maxResponseBytes?: number;
+  readonly timeoutMs?: number;
+  readonly handle: (
+    request: DshBoundaryRequest,
+    context: DshBoundaryContext,
+  ) => Promise<Response>;
+}