arxo-codegen 0.4.0__py3-none-any.whl

arxo_codegen/package.py

@@ -0,0 +1,565 @@
+#!/usr/bin/env python3
+"""Устанавливаемый пакет порождённой библиотеки (DECISION-0423 §2.7, шаг 5).
+
+    python3 package.py <ir.json> --target py --name NAME --version X.Y.Z --out DIR
+    python3 package.py <ir.json> --target ts --name @scope/name --version X.Y.Z --out DIR
+    python3 package.py <ir.json> --target go --name NAME --version X.Y.Z \\
+        --module example.com/org/name --out DIR
+
+Модель, рантайм и API печатают те же эмиттеры, что и поставка `deliver.py`:
+пакет меняет раскладку и импорты, но не семантику. Рантайм и модель лежат во
+внутреннем подкаталоге (TypeScript — `src/internal/`, Python — `_internal/`;
+в Go приватность даёт регистр имён, поэтому код — в корневом пакете модуля).
+Наружу выходят функции API, `info()` с паспортом поставки и машинная карта
+`api-map.json` «функция → вопрос или вход → StableId → правила → якоря
+источника». Раннер и план ворот остаются в проверочном комплекте; у Go есть
+команда `cmd/<пакет>-eval` с протоколом раннера (ответ — код 0, названный
+отказ — `{"refused": …}` и код 3).
+
+Имя пакета — параметр. Для канонов, которые публикует Arxo, принята семья
+`-lib` (DECISION-0423 §7, выбор владельца): `@arxo/canon-<имя>-lib` (npm),
+`arxo-canon-<имя>-lib` (PyPI), `github.com/arxohq/canon-<имя>-lib` (Go);
+`@arxo/canon-<имя>` без суффикса — пакет самого канона (DECISION-0349 §8). Минимальные версии тулчейнов — константы целей
+`TOOLCHAIN_MIN`, равные версиям проверок CI. TypeScript собирается при
+упаковке собственным тулчейном цели: пакет без `dist/` не устанавливается.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+import deliver as D  # noqa: E402
+import plan as P  # noqa: E402
+from core_support import CoreKitError  # noqa: E402
+
+FORMAT = "law.codegen-package/0.1"
+MAP_FORMAT = "law.codegen-api-map/0.1"
+# Версия ABI поверхности API (DECISION-0423 §2.8): имена функций по языку,
+# `Answer`, ошибки, конструкторы литерал-термов. Меняется вместе с
+# несовместимой правкой поверхности, а не с версией генератора.
+API_ABI = "law.codegen-api/1"
+VALUE_FORMAT = "law.codegen-value/1"
+TARGETS = ("py", "ts", "go")
+EXAMPLE_DATE = "2026-01-01"
+
+# Строки импортов плоской раскладки и их замены в пакете. Каждая строка
+# обязана встретиться ровно один раз: незнакомая форма эмиттера — отказ
+# упаковки, а не молча непереписанный импорт.
+PY_REWRITES = {
+    "model.py": [("import runtime as RT", "from . import runtime as RT")],
+    "evaluate.py": [("import runtime as RT", "from . import runtime as RT"),
+                    ("import model as _MODEL", "from . import model as _MODEL")],
+    "api_base.py": [("import runtime as RT", "from . import runtime as RT"),
+                    ("from evaluate import evaluate as _evaluate", "from .evaluate import evaluate as _evaluate")],
+    "api.py": [("from api_base import (", "from ._internal.api_base import ("),
+               ("import api_base as _base", "from ._internal import api_base as _base")],
+}
+PY_FLAT_IMPORT = re.compile(r"^\s*(import|from)\s+(runtime|model|evaluate|api_base|api)\b", re.M)
+TS_INTERNAL = ("runtime.ts", "evaluate.ts", "apiBase.ts")
+GO_FILES = ("runtime.go", "evaluate.go", "apiBase.go")
+
+
+class PackageError(Exception):
+    """Упаковка невозможна: названная причина, пакет не пишется."""
+
+
+def sha(data: bytes) -> str:
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def rewrite(text: str, pairs: list, where: str) -> str:
+    lines = text.split("\n")
+    for old, new in pairs:
+        hits = [i for i, line in enumerate(lines) if line.startswith(old)]
+        if len(hits) != 1:
+            raise PackageError(f"{where}: ожидалась одна строка «{old}», найдено {len(hits)}")
+        lines[hits[0]] = new + lines[hits[0]][len(old):]
+    return "\n".join(lines)
+
+
+def generator_version() -> str:
+    """Версия генератора: `pyproject.toml` рядом — исходники, иначе метаданные
+    установленного дистрибутива."""
+    pyproject = HERE / "pyproject.toml"
+    if pyproject.is_file():
+        import tomllib
+        return tomllib.loads(pyproject.read_text(encoding="utf-8"))["project"]["version"]
+    from importlib.metadata import version
+    return version("arxo-codegen")
+
+
+def core_kit_digest() -> str | None:
+    """SHA-256 манифеста настроенного комплекта ядра (у исходников без комплекта — нет)."""
+    import core_support
+    kit = core_support.core_kit_path()
+    return sha((Path(kit) / "manifest.json").read_bytes()) if kit else None
+
+
+def go_package_name(ir: dict) -> str:
+    """Имя пакета Go по умолчанию — последний сегмент имени канона без знаков."""
+    tail = str((ir.get("package") or {}).get("name") or "canon").split(".")[-1]
+    name = re.sub(r"[^a-z0-9]", "", tail.lower()) or "canon"
+    return name if not name[0].isdigit() else "p" + name
+
+
+def py_import_name(name: str) -> str:
+    """Имя импорта Python по имени дистрибутива (PEP 503: `-`, `.` → `_`)."""
+    base = re.sub(r"[^A-Za-z0-9]+", "_", name.split("/")[-1]).strip("_").lower() or "canon"
+    return base if not base[0].isdigit() else "p" + base
+
+
+# --- карта API и пример ------------------------------------------------------
+
+def function_names(lang: str, em, api: dict) -> tuple[dict, dict]:
+    """Имена функций цели: вход → (факт, отрицательный факт), вопрос → (вопрос, строки)."""
+    inputs, questions = em.api_names(api["inputs"]), em.api_names(api["questions"])
+    if lang == "py":
+        fi = {k: (f"fact_{v}", f"negated_{v}") for k, v in inputs.items()}
+        fq = {k: (f"ask_{v}", f"rows_{v}") for k, v in questions.items()}
+    elif lang == "ts":
+        fi = {k: (f"facts.{v}", f"negated.{v}") for k, v in inputs.items()}
+        fq = {k: (f"ask.{v}", f"rows.{v}") for k, v in questions.items()}
+    else:
+        fi = {k: (f"Fact{v}", f"Negated{v}") for k, v in inputs.items()}
+        fq = {k: (f"Ask{v}", f"Rows{v}") for k, v in questions.items()}
+    return fi, fq
+
+
+def api_map(ir: dict, world: list, pl: dict, lang: str, em, distribution: dict, digest: str) -> dict:
+    api = pl.get("api") or {"questions": [], "inputs": []}
+    negation = "negation" in (pl.get("capabilities") or ())
+    rule_ids = {P._slug(n["id"]): n["id"] for doc in [ir, *world] for n in doc.get("nodes", [])
+                if n.get("kind") == "rule"}
+    fi, fq = function_names(lang, em, api)
+    functions = []
+    for q in api["questions"]:
+        functions.append({
+            "kind": "question", "function": fq[q["name"]][0], "rowsFunction": fq[q["name"]][1],
+            "name": q["name"], "predicate": q["pred"], "params": q["params"], "labels": q.get("labels", []),
+            "inputs": q.get("inputs", []),
+            "rules": [{"id": rule_ids.get(s["rule"], s["rule"]), "labels": s.get("labels", []),
+                       "anchors": s.get("anchors", [])} for s in q.get("sources", [])]})
+    for i in api["inputs"]:
+        entry = {"kind": "input", "function": fi[i["name"]][0], "name": i["name"], "predicate": i["pred"],
+                 "params": i["params"], "labels": i.get("labels", [])}
+        if negation:
+            entry["negatedFunction"] = fi[i["name"]][1]
+        functions.append(entry)
+    return {"format": MAP_FORMAT, "target": lang, "package": ir.get("package"), "semanticHash": digest,
+            "distribution": distribution, "functions": functions}
+
+
+def _example_value(param: str, kind: str, lang: str, q: str = "") -> str | None:
+    """Литерал примера по объявленному типу; сущность одного типа — один id,
+    чтобы факты и вопрос говорили об одном объекте."""
+    local = re.sub(r"[^A-Za-z0-9]+", "-", param.split("#")[-1]).strip("-").lower() or "x"
+    go = lang == "go"
+    if kind == "text" and param == "urn:law:std#Text":
+        return f'{q}TextOf("пример")' if go else 'text("пример")'
+    if kind == "text":
+        return f'{q}EntityOf("urn:example:{local}-1")' if go else f'entity("urn:example:{local}-1")'
+    if kind == "money":
+        return f'{q}MoneyOf("100", "KZT")' if go else 'money("100", "KZT")'
+    if kind == "dec" and param == "urn:law:std#Integer":
+        return f"{q}IntegerOf(10)" if go else "integer(10)"
+    if kind == "dec" and param == "urn:law:std#Natural":
+        return f"{q}NaturalOf(10)" if go else "natural(10)"
+    if kind == "dec":
+        return f'{q}DecimalOf("10")' if go else 'decimal("10")'
+    if kind == "date":
+        return f'{q}DateOf("{EXAMPLE_DATE}")' if go else f'date("{EXAMPLE_DATE}")'
+    if kind == "bool":
+        return {"py": "boolean(True)", "ts": "boolean(true)", "go": f"{q}BooleanOf(true)"}[lang]
+    return None
+
+
+def _example_args(entry: dict, lang: str, q: str = "") -> list | None:
+    out = []
+    for param, kind in zip(entry["params"], entry["kinds"]):
+        value = _example_value(param, kind, lang, q)
+        if value is None:
+            return None
+        out.append(value)
+    return out
+
+
+def example(pl: dict, lang: str, em, import_path: str) -> str | None:
+    """Исполняемый пример README: факты по входам первого вопроса с
+    синтезируемыми аргументами и сам вопрос; приёмка запускает его как есть."""
+    api = pl.get("api") or {"questions": [], "inputs": []}
+    fi, fq = function_names(lang, em, api)
+    inputs = {i["pred"]: i for i in api["inputs"]}
+    for q in api["questions"]:
+        q_args = _example_args(q, lang, "lib." if lang == "go" else "")
+        if q_args is None:
+            continue
+        facts = []
+        for pred in q.get("inputs", []):
+            i = inputs.get(pred)
+            args = _example_args(i, lang, "lib." if lang == "go" else "") if i else None
+            if args is not None:
+                facts.append((fi[i["name"]][0], args))
+            if len(facts) == 6:
+                break
+        used = sorted({re.match(r"(?:lib\.)?(\w+)\(", a).group(1) for _f, args in facts for a in args}
+                      | {re.match(r"(?:lib\.)?(\w+)\(", a).group(1) for a in q_args})
+        ask = fq[q["name"]][0]
+        if lang == "py":
+            names = sorted({ask, *(f for f, _a in facts)}) + used
+            lines = [f"from {import_path} import {', '.join(names)}", "", "facts = ["]
+            lines += [f"    {f}({', '.join(a)})," for f, a in facts]
+            lines += ["]", f'answer = {ask}(facts, "{EXAMPLE_DATE}"{"".join(", " + a for a in q_args)})',
+                      "print(answer.truth_status, answer.evaluation_status)"]
+            return "\n".join(lines)
+        if lang == "ts":
+            names = ["ask", *(["facts"] if facts else [])] + used
+            lines = [f'import {{ {", ".join(names)} }} from "{import_path}";', "", "const known = ["]
+            lines += [f"  {f}({', '.join(a)})," for f, a in facts]
+            lines += ["];", f'const answer = {ask}(known, "{EXAMPLE_DATE}"{"".join(", " + a for a in q_args)});',
+                      'if (answer.resultKind === "PROPOSITION") console.log(answer.truthStatus, answer.evaluationStatus);']
+            return "\n".join(lines)
+        lines = ["package main", "", "import (", '\t"fmt"', "", f'\tlib "{import_path}"', ")", "",
+                 "func main() {", "\tfacts := []lib.Fact{"]
+        lines += [f"\t\tlib.{f}({', '.join(a)})," for f, a in facts]
+        lines += ["\t}", f'\tanswer, err := lib.{ask}(facts, "{EXAMPLE_DATE}"{"".join(", " + a for a in q_args)})',
+                  "\tif err != nil {", "\t\tpanic(err)", "\t}",
+                  "\tfmt.Println(answer.TruthStatus, answer.EvaluationStatus)", "}"]
+        return "\n".join(lines)
+    return None
+
+
+FENCE = {"py": "python", "ts": "ts", "go": "go"}
+
+
+def readme(ir: dict, lang: str, name: str, version: str, install: str, sample: str | None, mapping: dict) -> str:
+    package = ir.get("package") or {}
+    canon = f"{package.get('name')}@{package.get('version')}"
+    lines = [f"# {name}", "",
+             f"Исполняемая модель канона `{canon}` без движка правил: модуль порождён "
+             f"arxo-codegen из CLIR канона (профиль `core-executable`, DECISION-0188). "
+             "Ответ — статус истинности §62 и статус вычисления §175; доказательства и "
+             "хэшей воспроизводимости нет — за ними движок Arxo. Конструкция вне среза "
+             "генератора — названный отказ, а не другой ответ.", "",
+             "## Установка", "", "```sh", install, "```", ""]
+    if sample:
+        lines += ["## Пример", "", f"```{FENCE[lang]}", sample, "```", ""]
+    lines += ["## Функции", "", "| Функция | Вид | StableId |", "|---|---|---|"]
+    for f in mapping["functions"]:
+        kind = "вопрос" if f["kind"] == "question" else "вход"
+        lines.append(f"| `{f['function']}` | {kind} | `{f['predicate']}` |")
+    lines += ["", "Карта «функция → вопрос или вход → StableId → правила → якоря источника» — "
+              "`api-map.json`; паспорт поставки (канон, семантический хэш, мир, файлы) — "
+              "`info()`.", ""]
+    return "\n".join(lines)
+
+
+# --- раскладки целей ---------------------------------------------------------
+
+def _emit(pl: dict, em) -> tuple[str, str]:
+    return em.emit(pl), em.emit_api(pl)
+
+
+def layout_py(root: Path, em, pl: dict, name: str, version: str, ir: dict) -> dict:
+    imp = py_import_name(name)
+    pkg = root / "src" / imp
+    internal = pkg / "_internal"
+    internal.mkdir(parents=True)
+    model, api = _emit(pl, em)
+    sources = {n: (Path(em.__file__).parent / n).read_text(encoding="utf-8")
+               for n in ("runtime.py", "evaluate.py", "api_base.py")}
+    sources["model.py"] = model
+    for n, text in sources.items():
+        text = rewrite(text, PY_REWRITES.get(n, []), n)
+        if PY_FLAT_IMPORT.search(text):
+            raise PackageError(f"{n}: остался импорт плоской раскладки")
+        (internal / n).write_text(text, encoding="utf-8")
+    (internal / "__init__.py").write_text('"""Внутренняя часть пакета: рантайм, модель, единый вход."""\n',
+                                          encoding="utf-8")
+    api = rewrite(api, PY_REWRITES["api.py"], "api.py")
+    if PY_FLAT_IMPORT.search(api):
+        raise PackageError("api.py: остался импорт плоской раскладки")
+    (pkg / "api.py").write_text(api, encoding="utf-8")
+    (pkg / "py.typed").write_text("", encoding="utf-8")
+    package = ir.get("package") or {}
+    description = f"Исполняемая модель канона {package.get('name')} без движка (arxo-codegen)"
+    (pkg / "__init__.py").write_text("\n".join([
+        f'"""{name}: исполняемая модель канона {package.get("name")}@{package.get("version")} без движка.',
+        "",
+        "Функции `fact_*`, `ask_*`, `rows_*` и реестры `QUESTIONS`, `INPUTS` — из `api`;",
+        '`info()` отдаёт паспорт поставки (law.backend-delivery/1)."""',
+        "from .api import *  # noqa: F401,F403",
+        "from .api import INPUTS, NEGATED, QUESTIONS  # noqa: F401",
+        "",
+        "",
+        "def info() -> dict:",
+        '    """Паспорт поставки: канон, семантический хэш §209, мир, профиль, файлы."""',
+        "    from ._internal.passport import passport",
+        "    return passport()",
+        ""]), encoding="utf-8")
+    (root / "pyproject.toml").write_text("\n".join([
+        "[build-system]",
+        'requires = ["setuptools>=65"]',
+        'build-backend = "setuptools.build_meta"',
+        "",
+        "[project]",
+        f"name = {json.dumps(name)}",
+        f"version = {json.dumps(version)}",
+        f"description = {json.dumps(description, ensure_ascii=False)}",
+        'readme = "README.md"',
+        f'requires-python = ">={em.TOOLCHAIN_MIN}"',
+        "dependencies = []",
+        "",
+        "[tool.setuptools.packages.find]",
+        'where = ["src"]',
+        "",
+        "[tool.setuptools.package-data]",
+        f'{json.dumps(imp)} = ["py.typed", "api-map.json"]',
+        ""]), encoding="utf-8")
+    return {"import": imp, "install": f"pip install {name}", "api_map": pkg / "api-map.json",
+            "passport": lambda text: (internal / "passport.py").write_text(
+                '"""Паспорт поставки (law.backend-delivery/1), вшитый при упаковке."""\n'
+                "import json as _json\n\n"
+                f"_PASSPORT = {text!r}\n\n\n"
+                "def passport() -> dict:\n"
+                "    return _json.loads(_PASSPORT)\n", encoding="utf-8"),
+            "unhashed": {f"src/{imp}/_internal/passport.py"}}
+
+
+def layout_ts(root: Path, em, pl: dict, name: str, version: str, ir: dict) -> dict:
+    src = root / "src"
+    internal = src / "internal"
+    internal.mkdir(parents=True)
+    model, api = _emit(pl, em)
+    for n in TS_INTERNAL:
+        shutil.copyfile(Path(em.__file__).parent / n, internal / n)
+    (internal / "model.ts").write_text(model, encoding="utf-8")
+    if api.count('from "./apiBase"') != 3:
+        raise PackageError('api.ts: ожидались три импорта из "./apiBase"')
+    api = api.replace('from "./apiBase"', 'from "./internal/apiBase"')
+    if re.search(r'from "\./(runtime|model|evaluate)"', api):
+        raise PackageError("api.ts: остался импорт плоской раскладки")
+    (src / "api.ts").write_text(api, encoding="utf-8")
+    package = ir.get("package") or {}
+    (src / "index.ts").write_text("\n".join([
+        f"// {name}: исполняемая модель канона {package.get('name')}@{package.get('version')} без движка.",
+        "// Функции facts.*, ask.*, rows.* и реестры — из ./api; info() — паспорт поставки.",
+        'export * from "./api";',
+        'import { PASSPORT } from "./internal/passport";',
+        "",
+        "/** Паспорт поставки (law.backend-delivery/1): канон, семантический хэш §209, мир, файлы. */",
+        "export function info(): Record<string, unknown> {",
+        "  return JSON.parse(PASSPORT);",
+        "}",
+        ""]), encoding="utf-8")
+    (root / "tsconfig.json").write_text(json.dumps({"compilerOptions": {
+        "target": "es2022", "module": "commonjs", "lib": ["es2022"], "types": [], "strict": True,
+        "declaration": True, "rootDir": "src", "outDir": "dist"}, "include": ["src"]}, indent=2) + "\n",
+        encoding="utf-8")
+    (root / "package.json").write_text(json.dumps({
+        "name": name, "version": version,
+        "description": f"Исполняемая модель канона {package.get('name')} без движка (arxo-codegen)",
+        "main": "dist/index.js", "types": "dist/index.d.ts",
+        "exports": {".": {"types": "./dist/index.d.ts", "default": "./dist/index.js"},
+                    "./api-map.json": "./api-map.json", "./package.json": "./package.json"},
+        "files": ["dist", "src", "api-map.json", "law-backend.json", "README.md"],
+        "engines": {"node": f">={em.TOOLCHAIN_MIN}"}, "sideEffects": False},
+        ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+    def passport(text: str) -> None:
+        (internal / "passport.ts").write_text(
+            "// Паспорт поставки (law.backend-delivery/1), вшитый при упаковке.\n"
+            f"export const PASSPORT = {json.dumps(text, ensure_ascii=False)};\n", encoding="utf-8")
+    return {"import": name, "install": f"npm install {name}", "api_map": root / "api-map.json",
+            "passport": passport, "build": True,
+            "unhashed": {"src/internal/passport.ts", "dist/internal/passport.js", "dist/internal/passport.d.ts"}}
+
+
+def layout_go(root: Path, em, pl: dict, name: str, version: str, ir: dict, module: str, gopkg: str) -> dict:
+    model, api = _emit(pl, em)
+    files = {n: (Path(em.__file__).parent / n).read_text(encoding="utf-8") for n in GO_FILES}
+    files["model.go"], files["api.go"] = model, api
+    for n, text in files.items():
+        if len(re.findall(r"^package main$", text, re.M)) != 1:
+            raise PackageError(f"{n}: ожидалась одна строка «package main»")
+        (root / n).write_text(re.sub(r"^package main$", f"package {gopkg}", text, count=1, flags=re.M),
+                              encoding="utf-8")
+    (root / "eval.go").write_text("\n".join([
+        f"package {gopkg}", "",
+        "// EvaluateJSON — единый вход модели (DECISION-0423 §2.2): дело и вопрос в",
+        "// канонической форме §168/§172 → ответ профиля core-executable в JSON.",
+        "// Названный отказ среза — ошибка *RefusedError.",
+        "func EvaluateJSON(caseJSON, queryJSON []byte) (string, error) {",
+        "\treturn evaluate(caseJSON, queryJSON)",
+        "}", ""]), encoding="utf-8")
+    (root / "go.mod").write_text(f"module {module}\n\ngo {em.TOOLCHAIN_MIN}\n", encoding="utf-8")
+    command = root / "cmd" / f"{gopkg}-eval"
+    command.mkdir(parents=True)
+    (command / "main.go").write_text("\n".join([
+        f"// Команда {gopkg}-eval исполняет дело и вопрос канонической формы §168/§172",
+        "// и печатает ответ профиля core-executable: код 0 — ответ, код 3 — названный",
+        '// отказ среза в виде {"refused": текст}, как у раннера проверочного комплекта.',
+        "package main", "",
+        "import (", '\t"encoding/json"', '\t"errors"', '\t"fmt"', '\t"os"', "",
+        f'\tlib "{module}"', ")", "",
+        "func main() {",
+        "\tif len(os.Args) != 3 {",
+        f'\t\tfmt.Fprintln(os.Stderr, "использование: {gopkg}-eval дело.json вопрос.json")',
+        "\t\tos.Exit(2)",
+        "\t}",
+        "\tkase, err := os.ReadFile(os.Args[1])",
+        "\tif err != nil {", "\t\tfmt.Fprintln(os.Stderr, err)", "\t\tos.Exit(2)", "\t}",
+        "\tquery, err := os.ReadFile(os.Args[2])",
+        "\tif err != nil {", "\t\tfmt.Fprintln(os.Stderr, err)", "\t\tos.Exit(2)", "\t}",
+        "\tanswer, err := lib.EvaluateJSON(kase, query)",
+        "\tvar refused *lib.RefusedError",
+        "\tif errors.As(err, &refused) {",
+        '\t\tout, _ := json.Marshal(map[string]string{"refused": refused.Message})',
+        "\t\tfmt.Println(string(out))",
+        "\t\tos.Exit(3)",
+        "\t}",
+        "\tif err != nil {", "\t\tfmt.Fprintln(os.Stderr, err)", "\t\tos.Exit(1)", "\t}",
+        "\tfmt.Println(answer)",
+        "}", ""]), encoding="utf-8")
+
+    def passport(text: str) -> None:
+        (root / "passport.go").write_text("\n".join([
+            f"package {gopkg}", "",
+            "// Паспорт поставки (law.backend-delivery/1), вшитый при упаковке.",
+            f"const passportJSON = {json.dumps(text, ensure_ascii=False)}", "",
+            "// Info возвращает паспорт поставки: канон, семантический хэш §209, мир, файлы (JSON).",
+            "func Info() string { return passportJSON }", ""]), encoding="utf-8")
+    return {"import": module, "install": f"go get {module}@v{version}", "api_map": root / "api-map.json",
+            "passport": passport, "unhashed": {"passport.go"}}
+
+
+# --- сборка пакета -----------------------------------------------------------
+
+def build_ts(root: Path, em) -> None:
+    modules = em.toolchain()
+    if modules is None:
+        raise PackageError("тулчейн TypeScript недоступен: пакет без dist/ не устанавливается")
+    result = subprocess.run([str(modules / ".bin" / "tsc"), "-p", str(root / "tsconfig.json")],
+                            capture_output=True, text=True, check=False)
+    if result.returncode:
+        raise PackageError("сборка TypeScript отказала:\n" + (result.stdout + result.stderr)[-4000:])
+
+
+def package(ir: dict, lang: str, out: Path, *, name: str, version: str, module: str | None = None,
+            go_package: str | None = None, world: list | None = None, resources: dict | None = None) -> dict:
+    """Пакет одной цели в новый каталог `out`; возвращает паспорт."""
+    if lang not in TARGETS:
+        raise PackageError(f"цель {lang}: пакет печатается только для {', '.join(TARGETS)}")
+    if not re.fullmatch(r"\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?", version):
+        raise PackageError(f"версия пакета не по SemVer: {version}")
+    if lang == "go" and not module:
+        raise PackageError("цель go: нужен --module (путь модуля Go)")
+    out = Path(out)
+    if out.exists():
+        raise PackageError(f"каталог пакета уже существует: {out}")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    em = D.emitter(lang)
+    pl = P.build_plan(ir, world, resources=resources)
+    missing = D.missing_capabilities(pl, em)
+    if missing:
+        raise P.Refused(f"цель {lang} не поддерживает возможности плана: {', '.join(missing)}")
+    digest = D.semantic_hash(ir)
+    gopkg = go_package or go_package_name(ir)
+    distribution = {"format": FORMAT, "name": name, "version": version}
+    if lang == "go":
+        distribution.update(module=module, package=gopkg)
+    with tempfile.TemporaryDirectory(prefix="codegen-package-", dir=out.parent) as temp:
+        root = Path(temp) / "package"
+        root.mkdir()
+        if lang == "py":
+            spec = layout_py(root, em, pl, name, version, ir)
+        elif lang == "ts":
+            spec = layout_ts(root, em, pl, name, version, ir)
+        else:
+            spec = layout_go(root, em, pl, name, version, ir, module, gopkg)
+        mapping = api_map(ir, world or [], pl, lang, em, distribution, digest)
+        mapping_text = json.dumps(mapping, ensure_ascii=False, indent=1) + "\n"
+        spec["api_map"].write_text(mapping_text, encoding="utf-8")
+        if lang == "py":
+            (root / "api-map.json").write_text(mapping_text, encoding="utf-8")
+        sample = example(pl, lang, em, spec["import"])
+        (root / "README.md").write_text(readme(ir, lang, name, version, spec["install"], sample, mapping),
+                                        encoding="utf-8")
+        # Паспорт вшивается дважды одним текстом: заглушка до сборки (dist/
+        # TypeScript должен её видеть), настоящий — после хэширования файлов.
+        spec["passport"]("{}")
+        if spec.get("build"):
+            build_ts(root, em)
+        files = {p.relative_to(root).as_posix(): sha(p.read_bytes())
+                 for p in sorted(root.rglob("*")) if p.is_file()
+                 and p.relative_to(root).as_posix() not in spec["unhashed"]}
+        passport = {"format": D.FORMAT, "planVersion": pl["planVersion"], "target": lang,
+                    "package": ir.get("package"), "semanticHash": digest, "world": pl.get("world", []),
+                    "profile": getattr(em, "PROFILE", "core-executable"), "distribution": distribution,
+                    # DECISION-0423 §2.8: провенанс артефакта, а не доказательство вычисления.
+                    "generator": {"name": "arxo-codegen", "version": generator_version()},
+                    "coreKit": {"manifestSha256": core_kit_digest()},
+                    "capabilities": sorted(pl.get("capabilities") or ()),
+                    "api": {"abi": API_ABI, "valueFormat": VALUE_FORMAT},
+                    "files": files}
+        text = json.dumps(passport, ensure_ascii=False, indent=1) + "\n"
+        spec["passport"](text)
+        if spec.get("build"):
+            build_ts(root, em)
+        (root / "law-backend.json").write_text(text, encoding="utf-8")
+        shutil.move(str(root), str(out))
+    return passport
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("ir", type=Path, help="CLIR пакета (*.lawir.json)")
+    ap.add_argument("--target", choices=TARGETS, required=True)
+    ap.add_argument("--name", required=True, help="имя пакета (npm, PyPI) или его человекочитаемое имя (Go)")
+    ap.add_argument("--version", required=True, help="версия пакета по SemVer")
+    ap.add_argument("--module", help="путь модуля Go")
+    ap.add_argument("--go-package", help="имя пакета Go (по умолчанию — из имени канона)")
+    ap.add_argument("--out", type=Path, required=True, help="новый каталог пакета")
+    ap.add_argument("--dep", type=Path, action="append", default=[], help="CLIR зависимости (можно повторять)")
+    ap.add_argument("--corpus-root", type=Path, help="явный корень corpus/clir и packs (адаптер law-dsl)")
+    ap.add_argument("--resources", type=Path, help="JSON: URI → {path, sha256}; пути относительно JSON")
+    ap.add_argument("--core-kit", type=Path, help="проверенный комплект поддержки ядра")
+    args = ap.parse_args()
+    if args.core_kit:
+        import os
+        os.environ["LAW_CODEGEN_CORE_KIT"] = str(args.core_kit.resolve())
+    ir = json.loads(args.ir.read_text(encoding="utf-8"))
+    try:
+        from inputs import corpus_resources, dependency_index, load_resources
+        extra = [json.loads(p.read_text(encoding="utf-8")) for p in args.dep]
+        index = P.world_index(args.corpus_root) if args.corpus_root else {}
+        dependency_index(extra)
+        world = P.resolve_world(ir, index, extra) if ir.get("imports") else []
+        resources = load_resources(args.resources) if args.resources else (
+            corpus_resources([ir, *world], args.corpus_root) if args.corpus_root else {})
+        passport = package(ir, args.target, args.out, name=args.name, version=args.version,
+                           module=args.module, go_package=args.go_package, world=world, resources=resources)
+    except P.Refused as exc:
+        print(f"package: отказ плана — {exc}", file=sys.stderr)
+        return 2
+    except PackageError as exc:
+        print(f"package: {exc}", file=sys.stderr)
+        return 2
+    except CoreKitError as exc:
+        print(f"package: ошибка комплекта ядра — {exc}", file=sys.stderr)
+        return 1
+    print(f"package: {args.target} → {args.out} ({args.name} {args.version}, "
+          f"{passport['semanticHash'][:19]}…, файлов {len(passport['files'])})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())