kontract 0.1.0__tar.gz

kontract-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: kontract
+Version: 0.1.0
+Summary: Cross-repo fetch of a capability's process/contract tier (ADR-BCM-URBA-0016 / ADR-DSN-0002).
+Author: yremy
+License: Proprietary
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: kpack<3,>=2.0.0
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+
+# kontract
+
+Cross-repo fetch of a business capability's **process/contract tier** — the DDD
+tactical model (`aggregates.yaml`, `commands.yaml`, `policies.yaml`,
+`read-models.yaml`, `bus.yaml`, `api.yaml`, JSON schemas) that says HOW a
+capability is actually contracted, plus the `.bcm-provenance.json` pin that says
+which corpus commit it derives from (ADR-DSN-0001).
+
+Sibling of [`kpack`](https://github.com/papeete-hub/kpack), sharing its transport
+only: `kontract` depends on `kpack` as a library (`kpack.config`, `kpack.registry`,
+`kpack.remote`, `kpack.provenance`) and adds the one resolution step kpack doesn't
+have — a business context to the *solution* context that `refines` it
+(ADR-GCM-URBA-0006). See
+[`reliever-design/adr/ADR-DSN-0002`](https://github.com/papeete-foundry/reliever-design/blob/main/adr/ADR-DSN-0002-kontract-resolution.md)
+for the design record.
+
+## How it works
+
+```
+CAP_ID (e.g. BNK.RLVR.CAP.SUP.002.BEN)
+  -> business context (segs 0-1, e.g. BNK.RLVR)     -- kpack's own bootstrap --
+  -> ENTERPRISE (seg 0) -> kpack config -> registry repo -> vocab.yaml contexts:
+  -> confirm business context is registered                -- new: kontract's own step --
+  -> scan contexts for kind: solution, refines: <business context>  (exactly one expected)
+  -> that context's repo -> kpack.remote.resolve_repo_root (fetch + cache, same as kpack)
+  -> serve process/<CAP_ID>/ from the resolved checkout
+```
+
+No caching beyond kpack's own git-clone cache (`--cache-dir` / `--no-fetch` /
+`--fresh`) — every call is a fresh fetch by design.
+
+## Install
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+kontract fetch <CAP_ID> [--ref REF] [--repo-root PATH] [--cache-dir DIR]
+                         [--no-fetch] [--fresh] [--config PATH]
+                         [--registry-repo SLUG] [--registry-ref REF] [--compact]
+```
+
+Uses the same `~/.config/kpack/config.yaml` / `./.kpack.yaml` / `--config`
+enterprise -> registry bootstrap as `kpack` — no separate kontract config file.
+
+## Develop
+
+```bash
+make test     # pytest against a fake business+solution repo pair (tests/conftest.py)
+```

kontract-0.1.0/README.md

@@ -0,0 +1,53 @@
+# kontract
+
+Cross-repo fetch of a business capability's **process/contract tier** — the DDD
+tactical model (`aggregates.yaml`, `commands.yaml`, `policies.yaml`,
+`read-models.yaml`, `bus.yaml`, `api.yaml`, JSON schemas) that says HOW a
+capability is actually contracted, plus the `.bcm-provenance.json` pin that says
+which corpus commit it derives from (ADR-DSN-0001).
+
+Sibling of [`kpack`](https://github.com/papeete-hub/kpack), sharing its transport
+only: `kontract` depends on `kpack` as a library (`kpack.config`, `kpack.registry`,
+`kpack.remote`, `kpack.provenance`) and adds the one resolution step kpack doesn't
+have — a business context to the *solution* context that `refines` it
+(ADR-GCM-URBA-0006). See
+[`reliever-design/adr/ADR-DSN-0002`](https://github.com/papeete-foundry/reliever-design/blob/main/adr/ADR-DSN-0002-kontract-resolution.md)
+for the design record.
+
+## How it works
+
+```
+CAP_ID (e.g. BNK.RLVR.CAP.SUP.002.BEN)
+  -> business context (segs 0-1, e.g. BNK.RLVR)     -- kpack's own bootstrap --
+  -> ENTERPRISE (seg 0) -> kpack config -> registry repo -> vocab.yaml contexts:
+  -> confirm business context is registered                -- new: kontract's own step --
+  -> scan contexts for kind: solution, refines: <business context>  (exactly one expected)
+  -> that context's repo -> kpack.remote.resolve_repo_root (fetch + cache, same as kpack)
+  -> serve process/<CAP_ID>/ from the resolved checkout
+```
+
+No caching beyond kpack's own git-clone cache (`--cache-dir` / `--no-fetch` /
+`--fresh`) — every call is a fresh fetch by design.
+
+## Install
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+kontract fetch <CAP_ID> [--ref REF] [--repo-root PATH] [--cache-dir DIR]
+                         [--no-fetch] [--fresh] [--config PATH]
+                         [--registry-repo SLUG] [--registry-ref REF] [--compact]
+```
+
+Uses the same `~/.config/kpack/config.yaml` / `./.kpack.yaml` / `--config`
+enterprise -> registry bootstrap as `kpack` — no separate kontract config file.
+
+## Develop
+
+```bash
+make test     # pytest against a fake business+solution repo pair (tests/conftest.py)
+```

kontract-0.1.0/kontract/__init__.py

@@ -0,0 +1,17 @@
+"""kontract — cross-repo fetch of a capability's process/contract tier.
+
+Sibling of ``kpack`` (ADR-DSN-0001's "bet"): depends on it as a library for the
+registry/config/remote transport (``kpack.config``, ``kpack.registry``,
+``kpack.remote``, ``kpack.provenance``) and adds the one resolution step kpack
+doesn't have — a business context (e.g. ``BNK.RLVR``) to the *solution* context
+that ``refines`` it (ADR-GCM-URBA-0006), then serves ``process/<CAP_ID>/`` from
+that resolved repo.
+
+See ``reliever-design/adr/ADR-DSN-0002`` for the design record.
+"""
+
+__version__ = "0.1.0"
+
+# Envelope shape contract, mirroring kpack's own Rule 2 (SemVer, independent of
+# corpus/solution content).
+SCHEMA_VERSION = "1.0.0"

kontract-0.1.0/kontract/cli.py

@@ -0,0 +1,100 @@
+"""kontract command-line interface (plan §"CLI surface").
+
+One command, mirroring kpack's own flag conventions for consistency:
+
+  kontract fetch <CAP_ID> [--ref REF] [--repo-root PATH] [--cache-dir DIR]
+                           [--no-fetch] [--fresh] [--config PATH]
+                           [--registry-repo SLUG] [--registry-ref REF]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from kpack.errors import KpackError
+
+from . import __version__, envelope, model, resolver
+from .errors import KontractError
+from .resolver import Flags
+
+
+def _add_global_flags(p: argparse.ArgumentParser) -> None:
+    g = p.add_argument_group("resolution")
+    g.add_argument("--ref", default="main", help="solution-repo ref (tag / 40-char SHA / branch)")
+    g.add_argument("--repo-root", help="local checkout override for the solution repo")
+    g.add_argument("--cache-dir", help="cache dir (default ~/.cache/kpack)")
+    g.add_argument("--no-fetch", action="store_true", help="skip per-invocation git fetch")
+    g.add_argument("--fresh", action="store_true", help="wipe + re-clone the cache")
+    g.add_argument("--config", help="kpack config file (enterprise -> registry)")
+    g.add_argument("--registry-repo", help="override the resolved registry repo")
+    g.add_argument("--registry-ref", help="override the registry ref (default main)")
+    p.add_argument("--compact", action="store_true", help="one-line JSON")
+
+
+def _flags(args: argparse.Namespace) -> Flags:
+    return Flags(
+        ref=args.ref,
+        repo_root=args.repo_root,
+        cache_dir=args.cache_dir,
+        no_fetch=args.no_fetch,
+        fresh=args.fresh,
+        config=args.config,
+        registry_repo=args.registry_repo,
+        registry_ref=args.registry_ref,
+    )
+
+
+def _emit(obj, compact: bool) -> None:
+    if compact:
+        json.dump(obj, sys.stdout, separators=(",", ":"), sort_keys=False, default=str)
+    else:
+        json.dump(obj, sys.stdout, indent=2, sort_keys=False, default=str)
+    sys.stdout.write("\n")
+
+
+def _warn(env: dict) -> None:
+    for w in env.get("warnings", []):
+        print(f"warning: {w}", file=sys.stderr)
+
+
+def cmd_fetch(args) -> int:
+    resolved = resolver.resolve(args.capability_id, _flags(args))
+    body = model.get_model(resolved.solution_root, args.capability_id)
+    env = envelope.base_envelope(resolved, "fetch_process_model")
+    env.update(body)
+    _warn(env)
+    _emit(env, args.compact)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="kontract",
+        description="Cross-repo fetch of a capability's process/contract tier.",
+    )
+    parser.add_argument("--version", action="version", version=f"kontract {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("fetch", help="fetch a capability's process/contract model")
+    p.add_argument("capability_id")
+    _add_global_flags(p)
+    p.set_defaults(func=cmd_fetch)
+
+    return parser
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except (KontractError, KpackError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return getattr(exc, "exit_code", 1)
+    except BrokenPipeError:  # pragma: no cover
+        return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

kontract-0.1.0/kontract/envelope.py

@@ -0,0 +1,36 @@
+"""Envelope assembly for kontract, shaped like kpack's own (design consistency).
+
+Carries both resolved coordinates: the ``solution`` repo's provenance (reusing
+kpack's git-derived provenance helper) and, unless ``--repo-root`` short-circuited
+resolution, the ``registry`` binding that produced it — so a fetch is replayable.
+"""
+
+from __future__ import annotations
+
+from kpack.provenance import corpus_provenance
+
+from . import SCHEMA_VERSION, __version__
+from .resolver import Resolved
+
+
+def _solution_block(resolved: Resolved) -> dict:
+    prov = corpus_provenance(resolved.solution_root)
+    return {
+        "enterprise": resolved.business_context.split(".")[0],
+        "refines": resolved.business_context,
+        "context": resolved.solution_context,
+        "repo": resolved.solution_repo,
+        **prov,
+    }
+
+
+def base_envelope(resolved: Resolved, tool: str) -> dict:
+    env = {
+        "schema_version": SCHEMA_VERSION,
+        "engine": {"name": "kontract", "version": __version__},
+        "solution": _solution_block(resolved),
+        "tool": tool,
+    }
+    if resolved.registry_repo:
+        env["registry"] = {"repo": resolved.registry_repo, "ref": resolved.registry_ref}
+    return env

kontract-0.1.0/kontract/errors.py

@@ -0,0 +1,29 @@
+"""Typed errors with stable CLI exit codes (mirrors kpack.errors' convention).
+
+Exit codes:
+  0  success
+  1  unexpected error
+  2  unknown capability / bad target / no process model
+  3  context / registry resolution error (including ambiguous refines)
+  4  remote / git failure (raised as kpack.errors.RemoteError, passed through)
+"""
+
+from __future__ import annotations
+
+
+class KontractError(Exception):
+    """Base class for all kontract errors."""
+
+    exit_code = 1
+
+
+class TargetError(KontractError):
+    """Bad capability id, or no process model for it."""
+
+    exit_code = 2
+
+
+class ResolutionError(KontractError):
+    """The business -> solution context resolution failed."""
+
+    exit_code = 3

kontract-0.1.0/kontract/model.py

@@ -0,0 +1,90 @@
+"""Serve ``process/<CAP_ID>/`` from a resolved solution repo (plan step 3).
+
+A direct port of ``kpack.process.get_model`` — small and corpus-shape-specific,
+so a port rather than an import — with one addition kpack's version has no reason
+to make: also read and include ``.bcm-provenance.json``. ADR-DSN-0001 makes that
+file mandatory precisely so a consumer can see which corpus commit the contract
+was derived from; a missing one is surfaced as a warning, not silently dropped.
+
+Schemas live one level down, under ``process/<CAP_ID>/schemas/*.schema.json``
+(confirmed against the real reliever-design layout) — read explicitly from that
+subdirectory rather than only the model folder's top level.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import yaml
+
+from .errors import TargetError
+
+
+def _read_yaml(path: Path) -> dict:
+    raw = path.read_text()
+    try:
+        return {"raw": raw, "parsed": yaml.safe_load(raw), "parse_error": None}
+    except yaml.YAMLError as exc:
+        return {"raw": raw, "parsed": None, "parse_error": str(exc)}
+
+
+def get_model(solution_root: Path, capability_id: str) -> dict:
+    solution_root = Path(solution_root)
+    base = solution_root / "process" / capability_id
+    if not base.is_dir():
+        raise TargetError(f"no process model for {capability_id}")
+
+    model, schemas, files, warnings = {}, {}, [], []
+    readme = None
+    provenance = None
+
+    for f in sorted(base.iterdir()):
+        if f.is_dir():
+            continue
+        rel = str(f.relative_to(solution_root))
+        if f.name == ".bcm-provenance.json":
+            try:
+                provenance = json.loads(f.read_text())
+            except json.JSONDecodeError as exc:
+                warnings.append(f"invalid provenance {f.name}: {exc}")
+            files.append({"path": rel, "role": "provenance"})
+        elif f.suffix in (".yaml", ".yml"):
+            model[f.stem] = _read_yaml(f)
+            files.append({"path": rel, "role": f.stem})
+        elif f.name.endswith(".schema.json"):
+            try:
+                schemas[f.name] = json.loads(f.read_text())
+            except json.JSONDecodeError as exc:
+                warnings.append(f"invalid schema {f.name}: {exc}")
+            files.append({"path": rel, "role": "schema"})
+        elif f.name.lower() == "readme.md":
+            readme = f.read_text()
+            files.append({"path": rel, "role": "readme"})
+
+    schemas_dir = base / "schemas"
+    if schemas_dir.is_dir():
+        for f in sorted(schemas_dir.iterdir()):
+            if f.name.endswith(".schema.json"):
+                rel = str(f.relative_to(solution_root))
+                try:
+                    schemas[f.name] = json.loads(f.read_text())
+                except json.JSONDecodeError as exc:
+                    warnings.append(f"invalid schema {f.name}: {exc}")
+                files.append({"path": rel, "role": "schema"})
+
+    if provenance is None:
+        warnings.append(
+            f"no .bcm-provenance.json for {capability_id} — this model cannot prove "
+            f"which corpus commit it derives from (ADR-DSN-0001)"
+        )
+
+    return {
+        "target": {"kind": "process_model", "id": capability_id},
+        "model": model,
+        "schemas": schemas,
+        "provenance": provenance,
+        "readme": readme,
+        "files": files,
+        "warnings": warnings,
+    }

kontract-0.1.0/kontract/resolver.py

@@ -0,0 +1,127 @@
+"""Cross-repo resolution: business capability id -> solution repo checkout.
+
+The one resolution step kpack doesn't have (plan §"The actual gap to build", step 2):
+
+  1. Derive the capability's business context from segments 0-1 of its id.
+  2. Confirm that context is really registered (``kind: business``, or at least a
+     real registered context — never trust an unverified id shape).
+  3. Scan the same registry for the context with ``kind: solution`` whose
+     ``refines`` equals that business context (ADR-GCM-URBA-0006). Exactly one is
+     expected; zero or more than one is an error, not a silent pick.
+  4. Hand that context's ``repo`` to ``kpack.remote.resolve_repo_root`` — identical
+     fetch/cache/ref semantics kpack itself uses, no new transport code.
+
+Steps 1 (enterprise/registry bootstrap) and 4 (fetch) are reused verbatim from
+kpack; only the ``refines`` scan in between is new.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from kpack import config as config_mod
+from kpack import registry as registry_mod
+from kpack import remote
+
+from .errors import ResolutionError, TargetError
+
+
+@dataclass
+class Flags:
+    ref: str = "main"
+    repo_root: str | None = None
+    cache_dir: str | None = None
+    no_fetch: bool = False
+    fresh: bool = False
+    config: str | None = None
+    registry_repo: str | None = None
+    registry_ref: str | None = None
+
+
+@dataclass
+class Resolved:
+    capability_id: str
+    business_context: str
+    solution_context: str | None       # None when --repo-root short-circuits the registry
+    solution_repo: str | None
+    solution_root: Path
+    registry_repo: str | None
+    registry_ref: str | None
+
+
+def business_context_of(capability_id: str) -> str:
+    """The two-segment business context prefix of a capability id (ADR-GCM-URBA-0001)."""
+    parts = capability_id.split(".")
+    if len(parts) < 3:
+        raise TargetError(
+            f"{capability_id!r} is not a valid capability id "
+            f"(expected <ENTERPRISE>.<SCOPE>.<ASSET_TYPE>....)"
+        )
+    return ".".join(parts[:2])
+
+
+def find_solution_context(contexts: dict, business_context: str) -> str:
+    """The context with kind: solution and refines: business_context. Exactly one expected."""
+    business = contexts.get(business_context)
+    if business is None:
+        known = ", ".join(sorted(contexts))
+        raise ResolutionError(
+            f"context {business_context!r} is not in the authoritative registry. Known: {known}"
+        )
+    kind = business.get("kind")
+    if kind not in (None, "business"):
+        raise ResolutionError(
+            f"context {business_context!r} is registered with kind {kind!r}, expected "
+            f"'business' (or unspecified) for a capability id's context"
+        )
+
+    matches = sorted(
+        code
+        for code, entry in contexts.items()
+        if entry.get("kind") == "solution" and entry.get("refines") == business_context
+    )
+    if not matches:
+        raise ResolutionError(
+            f"no solution context refines {business_context!r} in the registry "
+            f"(expected exactly one entry with kind: solution and refines: {business_context})"
+        )
+    if len(matches) > 1:
+        raise ResolutionError(
+            f"multiple solution contexts refine {business_context!r}: {', '.join(matches)} "
+            f"— ambiguous, expected exactly one"
+        )
+    return matches[0]
+
+
+def resolve(capability_id: str, flags: Flags) -> Resolved:
+    cache = Path(flags.cache_dir) if flags.cache_dir else None
+    business_context = business_context_of(capability_id)
+
+    # --repo-root short-circuit: skip the registry entirely (dev / single checkout),
+    # same convention as kpack's own resolve_context.
+    if flags.repo_root:
+        solution_root = remote.resolve_repo_root(
+            business_context, flags.ref, cache_dir=cache, repo_root_override=flags.repo_root
+        )
+        return Resolved(capability_id, business_context, None, None, solution_root, None, None)
+
+    # Full bootstrap: enterprise -> registry -> contexts -> refines scan -> solution repo.
+    cfg = config_mod.load_config(flags.config)
+    enterprise = business_context.split(".")[0]
+    reg_repo, reg_ref = config_mod.resolve_registry(
+        cfg, enterprise, repo_override=flags.registry_repo, ref_override=flags.registry_ref
+    )
+    registry_root = remote.resolve_repo_root(
+        reg_repo, reg_ref, cache_dir=cache, no_fetch=flags.no_fetch, fresh=flags.fresh
+    )
+    contexts = registry_mod.load_contexts(registry_root)
+    solution_context = find_solution_context(contexts, business_context)
+    solution_repo = registry_mod.context_repo(contexts, solution_context)
+    solution_root = remote.resolve_repo_root(
+        solution_repo, flags.ref, cache_dir=cache, no_fetch=flags.no_fetch, fresh=flags.fresh
+    )
+    return Resolved(
+        capability_id, business_context, solution_context, solution_repo, solution_root,
+        reg_repo, reg_ref,
+    )

kontract-0.1.0/kontract.egg-info/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: kontract
+Version: 0.1.0
+Summary: Cross-repo fetch of a capability's process/contract tier (ADR-BCM-URBA-0016 / ADR-DSN-0002).
+Author: yremy
+License: Proprietary
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: kpack<3,>=2.0.0
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+
+# kontract
+
+Cross-repo fetch of a business capability's **process/contract tier** — the DDD
+tactical model (`aggregates.yaml`, `commands.yaml`, `policies.yaml`,
+`read-models.yaml`, `bus.yaml`, `api.yaml`, JSON schemas) that says HOW a
+capability is actually contracted, plus the `.bcm-provenance.json` pin that says
+which corpus commit it derives from (ADR-DSN-0001).
+
+Sibling of [`kpack`](https://github.com/papeete-hub/kpack), sharing its transport
+only: `kontract` depends on `kpack` as a library (`kpack.config`, `kpack.registry`,
+`kpack.remote`, `kpack.provenance`) and adds the one resolution step kpack doesn't
+have — a business context to the *solution* context that `refines` it
+(ADR-GCM-URBA-0006). See
+[`reliever-design/adr/ADR-DSN-0002`](https://github.com/papeete-foundry/reliever-design/blob/main/adr/ADR-DSN-0002-kontract-resolution.md)
+for the design record.
+
+## How it works
+
+```
+CAP_ID (e.g. BNK.RLVR.CAP.SUP.002.BEN)
+  -> business context (segs 0-1, e.g. BNK.RLVR)     -- kpack's own bootstrap --
+  -> ENTERPRISE (seg 0) -> kpack config -> registry repo -> vocab.yaml contexts:
+  -> confirm business context is registered                -- new: kontract's own step --
+  -> scan contexts for kind: solution, refines: <business context>  (exactly one expected)
+  -> that context's repo -> kpack.remote.resolve_repo_root (fetch + cache, same as kpack)
+  -> serve process/<CAP_ID>/ from the resolved checkout
+```
+
+No caching beyond kpack's own git-clone cache (`--cache-dir` / `--no-fetch` /
+`--fresh`) — every call is a fresh fetch by design.
+
+## Install
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+kontract fetch <CAP_ID> [--ref REF] [--repo-root PATH] [--cache-dir DIR]
+                         [--no-fetch] [--fresh] [--config PATH]
+                         [--registry-repo SLUG] [--registry-ref REF] [--compact]
+```
+
+Uses the same `~/.config/kpack/config.yaml` / `./.kpack.yaml` / `--config`
+enterprise -> registry bootstrap as `kpack` — no separate kontract config file.
+
+## Develop
+
+```bash
+make test     # pytest against a fake business+solution repo pair (tests/conftest.py)
+```

kontract-0.1.0/kontract.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+kontract/__init__.py
+kontract/cli.py
+kontract/envelope.py
+kontract/errors.py
+kontract/model.py
+kontract/resolver.py
+kontract.egg-info/PKG-INFO
+kontract.egg-info/SOURCES.txt
+kontract.egg-info/dependency_links.txt
+kontract.egg-info/entry_points.txt
+kontract.egg-info/requires.txt
+kontract.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_model.py
+tests/test_resolver.py

kontract-0.1.0/kontract.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kontract-0.1.0/kontract.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kontract = kontract.cli:main

kontract-0.1.0/kontract.egg-info/requires.txt

@@ -0,0 +1,6 @@
+kpack<3,>=2.0.0
+pyyaml<7,>=6.0
+
+[dev]
+pytest>=7
+build>=1.0

kontract-0.1.0/kontract.egg-info/top_level.txt

@@ -0,0 +1 @@
+kontract

kontract-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kontract"
+version = "0.1.0"
+description = "Cross-repo fetch of a capability's process/contract tier (ADR-BCM-URBA-0016 / ADR-DSN-0002)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "yremy" }]
+dependencies = ["kpack>=2.0.0,<3", "pyyaml>=6.0,<7"]
+
+[project.scripts]
+kontract = "kontract.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "build>=1.0"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["kontract*"]
+exclude = ["tests*"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

kontract-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kontract-0.1.0/tests/test_cli.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import json
+
+from kontract.cli import main
+from tests.conftest import CAP_ID
+
+
+def test_fetch_end_to_end(world, capsys):
+    rc = main(["fetch", CAP_ID])
+    assert rc == 0
+    out = json.loads(capsys.readouterr().out)
+    assert out["engine"]["name"] == "kontract"
+    assert out["solution"]["context"] == "ACME.SOL"
+    assert out["solution"]["refines"] == "ACME.BIZ"
+    assert out["registry"]["repo"] == str(world["registry"])
+    assert out["target"]["id"] == CAP_ID
+    assert "aggregates" in out["model"]
+    assert out["provenance"]["capability_id"] == CAP_ID
+
+
+def test_fetch_unknown_capability_exits_2(world, capsys):
+    rc = main(["fetch", "ACME.BIZ.CAP.NOPE.001"])
+    assert rc == 2
+    assert "no process model" in capsys.readouterr().err
+
+
+def test_fetch_ambiguous_solution_exits_3(world, capsys):
+    from tests.conftest import _commit, _write
+
+    contexts = [
+        {"code": "ACME.GOV", "kind": "governance", "repo": str(world["registry"])},
+        {"code": "ACME.BIZ", "kind": "business", "repo": "unused"},
+        {"code": "ACME.SOL", "kind": "solution", "repo": str(world["solution"]), "refines": "ACME.BIZ"},
+        {"code": "ACME.SOL2", "kind": "solution", "repo": str(world["solution"]), "refines": "ACME.BIZ"},
+    ]
+    _write(world["registry"], "vocab.yaml", {"contexts": contexts})
+    _commit(world["registry"], "registry v2 — add ambiguous second solution context")
+
+    rc = main(["fetch", CAP_ID, "--fresh"])
+    assert rc == 3
+    assert "ambiguous" in capsys.readouterr().err

kontract-0.1.0/tests/test_model.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import pytest
+
+from kontract.errors import TargetError
+from kontract.model import get_model
+from tests.conftest import CAP_ID
+
+
+def test_get_model_reads_yaml_readme_schemas_and_provenance(world):
+    m = get_model(world["solution"], CAP_ID)
+    assert m["target"] == {"kind": "process_model", "id": CAP_ID}
+    assert set(m["model"]) == {"aggregates", "commands"}
+    assert m["model"]["aggregates"]["parsed"] == {"aggregates": [{"name": "Score"}]}
+    assert m["readme"] == "Process model for Scoring."
+    assert "CMD.SCORE.schema.json" in m["schemas"]
+    assert m["provenance"]["capability_id"] == CAP_ID
+    assert m["warnings"] == []
+    paths = {f["path"] for f in m["files"]}
+    assert f"process/{CAP_ID}/schemas/CMD.SCORE.schema.json" in paths
+    assert f"process/{CAP_ID}/.bcm-provenance.json" in paths
+
+
+def test_get_model_warns_on_missing_provenance(world_no_provenance):
+    m = get_model(world_no_provenance["solution"], CAP_ID)
+    assert m["provenance"] is None
+    assert any("no .bcm-provenance.json" in w for w in m["warnings"])
+
+
+def test_get_model_missing_capability_raises(world):
+    with pytest.raises(TargetError):
+        get_model(world["solution"], "ACME.BIZ.CAP.NOPE.001")

kontract-0.1.0/tests/test_resolver.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import pytest
+
+from kontract.errors import ResolutionError, TargetError
+from kontract.resolver import Flags, business_context_of, find_solution_context, resolve
+from tests.conftest import CAP_ID
+
+
+def test_business_context_of():
+    assert business_context_of(CAP_ID) == "ACME.BIZ"
+
+
+def test_business_context_of_rejects_short_id():
+    with pytest.raises(TargetError):
+        business_context_of("ACME.BIZ")
+
+
+def test_find_solution_context_happy_path():
+    contexts = {
+        "ACME.BIZ": {"kind": "business", "repo": "x"},
+        "ACME.SOL": {"kind": "solution", "refines": "ACME.BIZ", "repo": "y"},
+    }
+    assert find_solution_context(contexts, "ACME.BIZ") == "ACME.SOL"
+
+
+def test_find_solution_context_unknown_business_context():
+    with pytest.raises(ResolutionError, match="not in the authoritative registry"):
+        find_solution_context({}, "ACME.BIZ")
+
+
+def test_find_solution_context_wrong_kind():
+    contexts = {"ACME.BIZ": {"kind": "solution", "repo": "x"}}
+    with pytest.raises(ResolutionError, match="expected 'business'"):
+        find_solution_context(contexts, "ACME.BIZ")
+
+
+def test_find_solution_context_zero_matches():
+    contexts = {"ACME.BIZ": {"kind": "business", "repo": "x"}}
+    with pytest.raises(ResolutionError, match="no solution context refines"):
+        find_solution_context(contexts, "ACME.BIZ")
+
+
+def test_find_solution_context_ambiguous():
+    contexts = {
+        "ACME.BIZ": {"kind": "business", "repo": "x"},
+        "ACME.SOL": {"kind": "solution", "refines": "ACME.BIZ", "repo": "y"},
+        "ACME.SOL2": {"kind": "solution", "refines": "ACME.BIZ", "repo": "z"},
+    }
+    with pytest.raises(ResolutionError, match="ambiguous"):
+        find_solution_context(contexts, "ACME.BIZ")
+
+
+def test_resolve_end_to_end(world):
+    resolved = resolve(CAP_ID, Flags())
+    assert resolved.business_context == "ACME.BIZ"
+    assert resolved.solution_context == "ACME.SOL"
+    assert resolved.solution_repo == str(world["solution"])
+    assert resolved.solution_root.is_dir()
+    assert (resolved.solution_root / "process" / CAP_ID).is_dir()
+    assert resolved.registry_repo == str(world["registry"])
+
+
+def test_resolve_repo_root_short_circuit(world):
+    resolved = resolve(CAP_ID, Flags(repo_root=str(world["solution"])))
+    assert resolved.solution_context is None
+    assert resolved.registry_repo is None
+    assert resolved.solution_root == world["solution"].resolve()