icdev-core 0.2.1__tar.gz

icdev_core-0.2.1/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: icdev-core
+Version: 0.2.1
+Summary: ICDEV shared core: domain declaration, path resolution, identity assertion and sensitivity labelling for the ICDEV[IT] and ICDEV[FT] parents.
+Author: Sovanna Chuon
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/icdev-ai/icdev-core
+Keywords: icdev,domain,paths,identity,sensitivity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: python-dotenv>=1.0
+
+# icdev-core
+
+The shared core of the ICDEV domain split: the small set of modules **both** parents need,
+carved out of [`icdev-ai/icdev`](https://github.com/icdev-ai/icdev) with history preserved.
+
+Distribution name is `icdev-core`; the **import root stays `icdev.core`**, unchanged.
+
+## What is in here, and why only this
+
+| module | answers |
+|---|---|
+| `paths` | *where is the repo root?* The ONE resolver. |
+| `domain` | *which parent is this checkout?* Reads `icdev_domain.yaml`. |
+| `context` | *may this process touch this database?* `assert_identity` / `check_identity` / `load_env`. |
+| `sensitivity` | *how sensitive is this table?* The one classification ladder. |
+| `schema/tables.yaml` | the core-owned table manifest. |
+
+The boundary was chosen from measurement, not from prose (`xcore-dec-01`). Two facts decided it:
+
+- **`icdev/core` has zero dependency on `tools/`.** It imports stdlib, plus `yaml` and
+  `dotenv` *locally inside the functions that need them* so importing the module pulls in no
+  third-party code. That is what made it separable at all.
+- **ICDEV[FT] already imports `icdev.core` in 32 files** and obtains it by putting the IT
+  checkout on `sys.path`. Replacing that `sys.path` coupling with a real dependency is the
+  whole point of this repo.
+
+Public API, derived from what the parents actually call rather than what was declared:
+
+```
+context.assert_identity  19    paths.repo_root                        13
+context.load_env          3    domain.{Domain, DomainError, load_domain}  1
+context.check_identity    1    sensitivity                    (IT row_security)
+```
+
+## `icdev` is a namespace package, and that is load-bearing
+
+This distribution ships `icdev/core/` and **no `icdev/__init__.py`**, so `icdev` is a PEP 420
+namespace package.
+
+Both this distribution and the ICDEV[IT] parent install into the same `icdev` name. A regular
+package has ONE `__path__`, so whichever were found first would win and the other's subpackages
+would silently vanish -- `icdev.core` unimportable in one direction, `icdev.tools` in the other.
+That is exactly what was measured before the fix: with the parent installed editable, `icdev`
+resolved to `C:/AI/ICDev/icdev` and installing this package beside it changed nothing at all.
+
+`pkgutil.extend_path` in **both** distributions was tried first and rejected. It merges
+`__path__` correctly, but only ONE `icdev/__init__.py` ever *executes* -- and when this one won,
+the parent's `_alias_tools_namespace()` never ran: the function that makes ~1,900
+`from tools.X import ...` imports resolve inside the parent's published wheel. An
+order-dependent silent break of every installed deployment is worse than the shadowing it was
+meant to fix.
+
+Shipping none here makes the parent's the only `__init__.py`, so it runs whatever the path
+order, and `extend_path` on the parent's side pulls `icdev/core/` in beside `icdev/tools/`.
+
+Pinned by `tests/test_namespace_package.py` and by a CI step that inspects the built wheel --
+because if setuptools' `namespaces` discovery ever defaults off, this repo publishes a wheel
+with no `icdev.core` in it and nothing here notices; the ImportError surfaces in a parent.
+
+## What is deliberately NOT in here
+
+**`shim.py` stayed in the IT parent.** It exists solely to make `tools.X` and
+`icdev.tools.X` resolve to one module object in IT's dual tree — and the FT parent has no
+`tools/` directory at all. Shipping it here would put one parent's layout knowledge inside
+the package both parents install.
+
+**The "functional core"** — storage, kanban, llm, genesis — stays in the IT parent. The
+carve-out cards used "core" for both that and this package; they are different by three
+orders of magnitude (3,690 files against 6), and only this one is separable today.
+
+## Why this repo is public
+
+Every module here was **already public** in `icdev-ai/icdev`, so publishing them separately
+exposes nothing new. A private core would be strictly worse: the *public* parent depends on
+it, so installing it in public CI would require a deploy token — a genuinely new secret in a
+public workflow, traded for hiding files that are already visible.
+
+## Using it
+
+```bash
+pip install -e ../icdev-core     # development, from a sibling checkout
+```
+
+```bash
+pip install icdev-core           # from PyPI (0.2.1+); `pip install icdev` pulls it in
+```
+
+Releases are semver tags. Publishing a GitHub release runs `.github/workflows/pypi-publish.yml`,
+which uploads to PyPI via Trusted Publishing; the tag must equal `v<pyproject version>`.
+For air-gapped installs, mirror the wheel to a local wheelhouse and use
+`pip install --no-index --find-links`. Pure Python, no build step.
+
+## Acceptance — what this package can and cannot prove
+
+The original criterion here read *"proven when ICDEV[FT] drops its `sys.path.insert` of the IT
+checkout and installs this package instead."* **That is not reachable, and stating it made a
+finished carve-out look permanently incomplete.** Measured on ICDEV[FT] 2026-08-27:
+
+| ICDEV[FT] modules importing | count | supplied by |
+|---|---|---|
+| `icdev.core.*` | 32 | **this package** |
+| `tools.*` | 72 | only the ICDEV[IT] checkout |
+
+`tools` exists because ICDEV[IT]'s `icdev/__init__.py` binds it to `icdev.tools`. This package
+ships `icdev/core/` and deliberately nothing else, so it cannot supply it and installing it
+cannot remove that checkout.
+
+**What IS achieved, and is verified:**
+
+- ICDEV[IT] no longer ships `icdev/core` and depends on this distribution (`xcore-cut-02`).
+- Both parents pin a tag, never a branch, and a parent's own gate fails if it calls a symbol the
+  pinned core does not export (`coherence_checker --check core_api`).
+- A change here is proven against ICDEV[IT] **before** merge by `core-compat.yml`, and against
+  ICDEV[FT] daily by the matching workflow in that repository (`xcore-compat-01`).
+
+**What is still outstanding:** ICDEV[FT]'s 72 `tools.*` imports. Removing that coupling is its
+own piece of work — a second extraction, or repointing those callers — and is not a side effect
+of this package existing.

icdev_core-0.2.1/README.md

@@ -0,0 +1,118 @@
+# icdev-core
+
+The shared core of the ICDEV domain split: the small set of modules **both** parents need,
+carved out of [`icdev-ai/icdev`](https://github.com/icdev-ai/icdev) with history preserved.
+
+Distribution name is `icdev-core`; the **import root stays `icdev.core`**, unchanged.
+
+## What is in here, and why only this
+
+| module | answers |
+|---|---|
+| `paths` | *where is the repo root?* The ONE resolver. |
+| `domain` | *which parent is this checkout?* Reads `icdev_domain.yaml`. |
+| `context` | *may this process touch this database?* `assert_identity` / `check_identity` / `load_env`. |
+| `sensitivity` | *how sensitive is this table?* The one classification ladder. |
+| `schema/tables.yaml` | the core-owned table manifest. |
+
+The boundary was chosen from measurement, not from prose (`xcore-dec-01`). Two facts decided it:
+
+- **`icdev/core` has zero dependency on `tools/`.** It imports stdlib, plus `yaml` and
+  `dotenv` *locally inside the functions that need them* so importing the module pulls in no
+  third-party code. That is what made it separable at all.
+- **ICDEV[FT] already imports `icdev.core` in 32 files** and obtains it by putting the IT
+  checkout on `sys.path`. Replacing that `sys.path` coupling with a real dependency is the
+  whole point of this repo.
+
+Public API, derived from what the parents actually call rather than what was declared:
+
+```
+context.assert_identity  19    paths.repo_root                        13
+context.load_env          3    domain.{Domain, DomainError, load_domain}  1
+context.check_identity    1    sensitivity                    (IT row_security)
+```
+
+## `icdev` is a namespace package, and that is load-bearing
+
+This distribution ships `icdev/core/` and **no `icdev/__init__.py`**, so `icdev` is a PEP 420
+namespace package.
+
+Both this distribution and the ICDEV[IT] parent install into the same `icdev` name. A regular
+package has ONE `__path__`, so whichever were found first would win and the other's subpackages
+would silently vanish -- `icdev.core` unimportable in one direction, `icdev.tools` in the other.
+That is exactly what was measured before the fix: with the parent installed editable, `icdev`
+resolved to `C:/AI/ICDev/icdev` and installing this package beside it changed nothing at all.
+
+`pkgutil.extend_path` in **both** distributions was tried first and rejected. It merges
+`__path__` correctly, but only ONE `icdev/__init__.py` ever *executes* -- and when this one won,
+the parent's `_alias_tools_namespace()` never ran: the function that makes ~1,900
+`from tools.X import ...` imports resolve inside the parent's published wheel. An
+order-dependent silent break of every installed deployment is worse than the shadowing it was
+meant to fix.
+
+Shipping none here makes the parent's the only `__init__.py`, so it runs whatever the path
+order, and `extend_path` on the parent's side pulls `icdev/core/` in beside `icdev/tools/`.
+
+Pinned by `tests/test_namespace_package.py` and by a CI step that inspects the built wheel --
+because if setuptools' `namespaces` discovery ever defaults off, this repo publishes a wheel
+with no `icdev.core` in it and nothing here notices; the ImportError surfaces in a parent.
+
+## What is deliberately NOT in here
+
+**`shim.py` stayed in the IT parent.** It exists solely to make `tools.X` and
+`icdev.tools.X` resolve to one module object in IT's dual tree — and the FT parent has no
+`tools/` directory at all. Shipping it here would put one parent's layout knowledge inside
+the package both parents install.
+
+**The "functional core"** — storage, kanban, llm, genesis — stays in the IT parent. The
+carve-out cards used "core" for both that and this package; they are different by three
+orders of magnitude (3,690 files against 6), and only this one is separable today.
+
+## Why this repo is public
+
+Every module here was **already public** in `icdev-ai/icdev`, so publishing them separately
+exposes nothing new. A private core would be strictly worse: the *public* parent depends on
+it, so installing it in public CI would require a deploy token — a genuinely new secret in a
+public workflow, traded for hiding files that are already visible.
+
+## Using it
+
+```bash
+pip install -e ../icdev-core     # development, from a sibling checkout
+```
+
+```bash
+pip install icdev-core           # from PyPI (0.2.1+); `pip install icdev` pulls it in
+```
+
+Releases are semver tags. Publishing a GitHub release runs `.github/workflows/pypi-publish.yml`,
+which uploads to PyPI via Trusted Publishing; the tag must equal `v<pyproject version>`.
+For air-gapped installs, mirror the wheel to a local wheelhouse and use
+`pip install --no-index --find-links`. Pure Python, no build step.
+
+## Acceptance — what this package can and cannot prove
+
+The original criterion here read *"proven when ICDEV[FT] drops its `sys.path.insert` of the IT
+checkout and installs this package instead."* **That is not reachable, and stating it made a
+finished carve-out look permanently incomplete.** Measured on ICDEV[FT] 2026-08-27:
+
+| ICDEV[FT] modules importing | count | supplied by |
+|---|---|---|
+| `icdev.core.*` | 32 | **this package** |
+| `tools.*` | 72 | only the ICDEV[IT] checkout |
+
+`tools` exists because ICDEV[IT]'s `icdev/__init__.py` binds it to `icdev.tools`. This package
+ships `icdev/core/` and deliberately nothing else, so it cannot supply it and installing it
+cannot remove that checkout.
+
+**What IS achieved, and is verified:**
+
+- ICDEV[IT] no longer ships `icdev/core` and depends on this distribution (`xcore-cut-02`).
+- Both parents pin a tag, never a branch, and a parent's own gate fails if it calls a symbol the
+  pinned core does not export (`coherence_checker --check core_api`).
+- A change here is proven against ICDEV[IT] **before** merge by `core-compat.yml`, and against
+  ICDEV[FT] daily by the matching workflow in that repository (`xcore-compat-01`).
+
+**What is still outstanding:** ICDEV[FT]'s 72 `tools.*` imports. Removing that coupling is its
+own piece of work — a second extraction, or repointing those callers — and is not a side effect
+of this package existing.

icdev_core-0.2.1/icdev/core/__init__.py

@@ -0,0 +1,22 @@
+# CUI // SP-CTI
+"""ICDEV core contract — the seam between the domain-neutral kernel and a parent.
+
+A parent (ICDEV[IT], ICDEV[FT], ...) declares itself in an ``icdev_domain.yaml``
+at its repository root. This package reads that declaration and answers the
+three questions every kernel module used to answer for itself, 2,054 times
+over, with ``Path(__file__).resolve().parent...``:
+
+* :mod:`icdev.core.paths`   — where is the repository root and its data?
+* :mod:`icdev.core.domain`  — which domain is this, and what did it declare?
+* :mod:`icdev.core.context` — is this process allowed to run HERE, against
+  THIS database? (``assert_identity``)
+
+Nothing in this package imports anything outside the standard library and
+PyYAML, so it can be imported before ``tools.db.storage`` and from either the
+``tools.*`` shim or the ``icdev.tools.*`` canonical namespace.
+
+Programme: docs/programmes/icdev-domain-split.md (xit-decl-01).
+"""
+from __future__ import annotations
+
+__all__ = ["paths", "domain", "context"]

icdev_core-0.2.1/icdev/core/context.py

@@ -0,0 +1,205 @@
+# CUI // SP-CTI
+"""Process identity: is THIS process allowed to run HERE, against THIS database?
+
+Two ICDEV parents run on one machine, share one shell and one PostgreSQL
+server, and both read ``<PREFIX>_PG_DATABASE`` / ``<PREFIX>_DATABASE_URL``
+from the process environment. An ICDEV[FT] session that inherits ICDEV[IT]'s
+``.env`` would open ``icdev`` and write trading rows into it; nothing today
+would notice. :func:`assert_identity` is the refusal, called at the start of
+every long-lived or state-changing entry point (dashboard, genesis daemon,
+``tools/db/migrate.py``, ``tools/kanban/cli.py``).
+
+The check is FAIL-CLOSED ON A DECLARED MISMATCH and NEVER on silence: a
+process whose env names no database at all is reported ``unmeasured`` and
+allowed through, because SQLite-only deployments, CI and tests legitimately
+run without one. A declaration that lists no ``db.databases`` asserts
+nothing and is likewise ``unmeasured``.
+
+    python -m icdev.core.context --check          # human summary, exit 1 on mismatch
+    python -m icdev.core.context --check --json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from icdev.core import paths as core_paths
+from icdev.core.domain import Domain, DomainError, load_domain
+
+IDENTITY_GUARD_ENV = "ICDEV_IDENTITY_GUARD"  # =0 -> report only, never refuse
+
+
+class IdentityMismatch(RuntimeError):
+    """The process environment names a database this parent did not declare."""
+
+
+@dataclass(frozen=True)
+class IdentityReport:
+    domain_key: str
+    domain_name: str
+    domain_source: str
+    root: str
+    database_declared: tuple[str, ...]
+    database_observed: str | None
+    database_source: str | None  # name_env | dsn_env | None
+    verdict: str  # match | mismatch | unmeasured
+    enforced: bool
+    detail: str
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["database_declared"] = list(self.database_declared)
+        return d
+
+
+def _database_from_dsn(dsn: str) -> str | None:
+    """Return the database name from a libpq URL, or None when it has none."""
+    try:
+        parts = urlsplit(dsn)
+    except ValueError:
+        return None
+    if parts.scheme not in ("postgresql", "postgres"):
+        return None
+    name = parts.path.lstrip("/")
+    return name or None
+
+
+def observed_database(domain: Domain, environ: os._Environ | dict | None = None) -> tuple[str | None, str | None]:
+    """Return ``(database_name, which_env_var)`` as the process env declares it.
+
+    ``name_env`` wins over ``dsn_env`` because that is the precedence
+    ``tools/db/storage.py`` gives ``ICDEV_PG_DATABASE`` when both are set for
+    the keyword form; a DSN's path is consulted only when the name is absent.
+    """
+    env = os.environ if environ is None else environ
+    name = (env.get(domain.db.name_env) or "").strip()
+    if name:
+        return name, domain.db.name_env
+    dsn = (env.get(domain.db.dsn_env) or "").strip()
+    if dsn:
+        parsed = _database_from_dsn(dsn)
+        if parsed:
+            return parsed, domain.db.dsn_env
+    return None, None
+
+
+def load_env(root: Path | None = None) -> Path | None:
+    """Load ``<root>/.env`` (the PARENT's, never cwd's). Returns the path loaded."""
+    root = root or core_paths.repo_root()
+    env_file = root / ".env"
+    if not env_file.is_file():
+        return None
+    try:
+        from dotenv import load_dotenv
+    except ImportError:  # pragma: no cover — dotenv is a declared dependency
+        return None
+    load_dotenv(env_file, override=False)
+    return env_file
+
+
+def check_identity(
+    *,
+    anchor: str | os.PathLike[str] | None = None,
+    domain: Domain | None = None,
+    environ: dict | None = None,
+) -> IdentityReport:
+    """Compute the identity verdict without raising."""
+    dom = domain or load_domain(anchor=anchor)
+    observed, which = observed_database(dom, environ)
+    declared = tuple(dom.db.databases)
+    enforced = os.environ.get(IDENTITY_GUARD_ENV, "1").strip().lower() not in ("0", "false", "no", "monitor")
+    if not declared:
+        verdict, detail = "unmeasured", "the declaration lists no db.databases, so it asserts nothing"
+    elif observed is None:
+        verdict, detail = "unmeasured", (
+            f"neither {dom.db.name_env} nor {dom.db.dsn_env} names a database in this process"
+        )
+    elif observed in declared:
+        verdict, detail = "match", f"{which}={observed} is declared by {dom.key}"
+    else:
+        verdict, detail = "mismatch", (
+            f"{which} names database {observed!r} but domain {dom.key!r} declares only "
+            f"{list(declared)} — this process is running against another parent's database"
+        )
+    return IdentityReport(
+        domain_key=dom.key,
+        domain_name=dom.name,
+        domain_source=dom.source,
+        root=str(dom.root),
+        database_declared=declared,
+        database_observed=observed,
+        database_source=which,
+        verdict=verdict,
+        enforced=enforced,
+        detail=detail,
+    )
+
+
+def assert_identity(
+    *,
+    anchor: str | os.PathLike[str] | None = None,
+    domain: Domain | None = None,
+    environ: dict | None = None,
+) -> IdentityReport:
+    """Refuse (``IdentityMismatch``) on a declared mismatch; return the report otherwise.
+
+    Stand it down with ``ICDEV_IDENTITY_GUARD=0`` (the report is still
+    computed and returned, so a caller can log it), never with a shell
+    neutraliser.
+    """
+    report = check_identity(anchor=anchor, domain=domain, environ=environ)
+    if report.verdict == "mismatch" and report.enforced:
+        raise IdentityMismatch(report.detail)
+    return report
+
+
+def describe(anchor: str | os.PathLike[str] | None = None) -> dict:
+    """Everything ``icdev status`` prints about where and who this process is."""
+    out: dict = {"paths": core_paths.describe(anchor)}
+    try:
+        dom = load_domain(anchor=anchor)
+    except DomainError as exc:
+        out["domain"] = None
+        out["error"] = str(exc)
+        return out
+    out["domain"] = dom.to_dict()
+    out["identity"] = check_identity(domain=dom).to_dict()
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--check", action="store_true", help="exit 1 on a declared mismatch")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--no-env", action="store_true", help="do not load <root>/.env first")
+    args = ap.parse_args(argv)
+
+    if not args.no_env:
+        load_env()
+    try:
+        info = describe()
+    except DomainError as exc:
+        print(f"domain declaration error: {exc}", file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps(info, indent=2))
+    else:
+        d = info.get("domain") or {}
+        ident = info.get("identity") or {}
+        print(f"domain   : {d.get('key')} ({d.get('name')}) from {d.get('source')}")
+        print(f"root     : {info['paths']['root']}  [{info['paths']['source']}]")
+        print(f"database : declared {d.get('db', {}).get('databases')} observed "
+              f"{ident.get('database_observed')!r} via {ident.get('database_source')}")
+        print(f"identity : {ident.get('verdict', 'unknown').upper()} — {ident.get('detail', info.get('error'))}")
+    if args.check and (info.get("identity") or {}).get("verdict") == "mismatch":
+        return 1
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())