P271 — AIEP — Single-Source Locked-Kernel Shim Distribution Architecture

Publication Date: 2026-04-12 Status: Open Source Prior Art Disclosure Licence: Apache License 2.0 Author/Organisation: Phatfella Limited Schema: AIEP_OS_SPEC_TEMPLATE v1.0.1 — https://aiep.dev/schemas/aiep-os-spec-template/v1.0.1 Patent ID: P271 Classification: OS — Open Source Prior Art Implemented in: AIEP GENOME SDK src/aiep_genome/kernel/canon.py (Layer 1 shim) Related filings: GB2519711.2 (AIEP Core Protocol)

Field of the Invention

[0001] The disclosure relates to software distribution architectures for cryptographically-verifiable protocol implementations.

[0002] More particularly, the disclosure concerns a two-layer shim architecture for distributing a canonical hash kernel as an installable package while preserving the ability for any consumer to verify, at runtime, that the installed kernel is identical — byte for byte — to a declared cryptographic reference, without requiring the consumer to trust the package distribution channel.

Framework Context

[0003] This disclosure operates within the AIEP framework.

[0004] The AIEP canonical hash kernel (canon.py) implements deterministic hash primitives — canonical_json(), concat_hash(), sha256_hex() — whose outputs must be identical across all conforming implementations in all languages and environments. Any byte difference in the kernel produces a different hash for the same input, silently breaking cross-platform protocol artefact equivalence.

[0005] This disclosure describes the architecture by which that kernel file is distributed as an installable Python package while ensuring that the distributed file and the authority reference file are the same object.

Background

[0006] Software package distribution systems — including pip (Python), npm (JavaScript), and cargo (Rust) — allow authors to publish versioned packages installable from a central registry. The installed package may differ from the source repository in several ways: it may be built from a compiled wheel, transformed by a packaging tool, or served from a cache. The version label of the installed package does not guarantee bit-for-bit identity with the source file at a given commit.

[0007] For protocols that require byte-identical implementations across deployments, a version label is insufficient for conformance assurance. Two implementations may both claim version 1.0.3 compatibility while containing different bytes in their critical hash-computation functions — either through divergent build toolchains, post-publication patch releases, or downstream modifications.

[0008] A further problem arises with packages that have multiple source files implementing related functionality: without a single designated authority file, a consumer does not know which file to hash for verification, and canonical logic may be duplicated in multiple locations that can diverge over time.

[0009] Existing systems do not provide:

(a) a designated single authority file for all canonical hash logic whose SHA-256 hash constitutes the protocol conformance pin; (b) a shim layer that loads the authority file dynamically at import time via an absolute path derived from the package’s own installation location, independent of sys.path, PYTHONPATH, or virtual environment configuration; (c) a GENOME_LOCKFILE.json record binding the declared authority file hash to a specific kernel version identifier, enabling downstream consumers to both pin to a version label and verify the underlying bytes; (d) a hash re-export pattern enabling downstream repositories to record their expected kernel hash independently and detect version skew without querying the package registry; or (e) a CI enforcement mechanism that verifies the shim contains no canonical logic and that the authority file hash matches the lockfile declaration.

[0010] There exists a need for a distribution architecture that enables a cryptographic protocol kernel to be installable via standard package management while preserving runtime-verifiable byte identity between the installed package and the declared authority reference.

Summary of the Disclosure

[0011] A two-layer kernel distribution architecture is provided for a cryptographic protocol implementation package.

[0012] A Layer 0 authority file (kernel/canon/canon.py) is designated as the single source of all canonical hash logic. The SHA-256 hash of this file is recorded in a GENOME_LOCKFILE.json at the repository root under layer_0_locks.kernel_files.

[0013] A Layer 1 shim file (src/aiep_genome/kernel/canon.py) is placed at the importable package path. The shim contains no canonical logic. At import time, the shim resolves an absolute filesystem path to the Layer 0 authority file using:

Path(__file__).resolve().parents[N] / "kernel" / "canon" / "canon.py"

where __file__ is the shim file’s own path and parents[N] traverses to the repository root. This path is position-independent: it does not depend on sys.path, PYTHONPATH, or the installed virtual environment layout.

[0014] The shim loads the Layer 0 authority file using importlib.util.spec_from_file_location with the resolved absolute path and re-exports all public symbols. Downstream consumers calling from aiep_genome import canonical_json execute the Layer 0 authority file’s implementation in all cases.

[0015] A kernel_bundle_hash field in GENOME_LOCKFILE.json records the SHA-256 of the Layer 0 authority file at the time of the version release. Any consumer can verify the installed kernel at startup by computing SHA-256(kernel/canon/canon.py) and comparing it to the declared hash.

[0016] Downstream repositories that depend on the kernel record their own expected kernel_bundle_hash in their own GENOME_LOCKFILE.json. This enables detection of version skew — a consumer that expects hash A but finds hash B installed detects a mismatch without querying any external registry.

[0017] The technical effect is modification of computing system operation such that a distributed cryptographic protocol kernel can be installed via standard package management while remaining byte-verifiable at runtime against a declared hash, with no dependency on the publisher’s infrastructure or the package registry’s integrity.

Brief Description of the Drawings

[0018] Figure 1 illustrates the two-layer architecture showing Layer 0 (authority file), Layer 1 (shim), and the import path taken by downstream consumers.

[0019] Figure 2 illustrates the GENOME_LOCKFILE.json hash chain: the authority file hash recorded in the SDK lockfile, and the pinned_kernel_hash recorded in downstream consumer lockfiles.

[0020] Figure 3 illustrates the startup verification flow by which a consuming application asserts hash equality between the installed authority file and the declared kernel_bundle_hash.

ASCII Drawings

Figure 1 — Two-Layer Import Architecture

Downstream consumer call:
  from aiep_genome import canonical_json

        +-------------------------------------------+
        |   Layer 1 — Shim (package path)           |
        |   src/aiep_genome/kernel/canon.py          |
        |                                           |
        |   NO canonical logic.                     |
        |   Resolves:                               |
        |     abs_path = Path(__file__).parents[3]  |
        |               / "kernel/canon/canon.py"   |
        |                                           |
        |   Loads Layer 0 via spec_from_file_location|
        |   Exports all symbols from Layer 0.        |
        +------------------+------------------------+
                           |
                           | spec_from_file_location (absolute path)
                           v
        +-------------------------------------------+
        |   Layer 0 — Authority File                |
        |   kernel/canon/canon.py                   |
        |                                           |
        |   ALL canonical logic lives here.         |
        |   SHA-256 of this file =                  |
        |     kernel_bundle_hash in LOCKFILE        |
        +-------------------------------------------+

Figure 2 — Hash Pinning Chain

AIEP-GENOME-SDK
  GENOME_LOCKFILE.json
    "kernel_bundle_hash": H(kernel/canon/canon.py)
            |
            | re-exported to downstream repos
            v
AIEP-VECTORS GENOME_LOCKFILE.json
    "kernel_bundle_hash": same H
            |
AIEP-MINER GENOME_LOCKFILE.json
    "pinned_kernel_hash": same H

Detailed Description of Embodiments

Layer 0 — Authority File

[0021] The Layer 0 authority file is kernel/canon/canon.py at the root of the genome-sdk repository. This file contains all implementations of: canonical_json(), concat_hash(), sha256_hex(), _canon_number_str(), _norm_object(), and all related canonical primitives. No other file in the package contains canonical logic.

[0022] The single-source rule is: Any change to AIEP canonicalisation behaviour MUST be applied to kernel/canon/canon.py only. This rule is enforced by the test suite, which imports primitives from both the Layer 0 path and the Layer 1 shim path and asserts identical outputs. If logic were duplicated in another file and diverged, test failure occurs before the divergence can reach any deployment.

Layer 1 — Shim

[0023] The Layer 1 shim file is at the Python package’s importable path. It contains:

import importlib.util as _ilu
import pathlib as _pl

_CANON_PATH = (
    _pl.Path(__file__).resolve().parents[3]
    / "kernel" / "canon" / "canon.py"
)
_spec = _ilu.spec_from_file_location("_aiep_canon_layer0", _CANON_PATH)
_mod = _ilu.module_from_spec(_spec)
_spec.loader.exec_module(_mod)

canonical_json  = _mod.canonical_json
concat_hash     = _mod.concat_hash
sha256_hex      = _mod.sha256_hex

[0024] parents[3] is computed from the shim’s own __file__. Given the directory structure src/aiep_genome/kernel/canon.py, parents[0] is src/aiep_genome/kernel/, parents[1] is src/aiep_genome/, parents[2] is src/, and parents[3] is the repository root. This path arithmetic is fixed at implementation time and does not vary with the execution environment.

[0025] The use of spec_from_file_location with the absolute path bypasses Python’s sys.path import resolution. The Layer 0 file is loaded as a module from its absolute disk location regardless of what entries are in sys.path, PYTHONPATH, or the virtual environment’s site-packages directory.

GENOME_LOCKFILE.json

[0026] The GENOME_LOCKFILE.json at the repository root records:

{
  "LOCKFILE_VERSION": "1.0.3",
  "layer_0_locks": {
    "kernel_bundle_hash": "<SHA-256 of kernel/canon/canon.py>",
    "kernel_files": {
      "kernel/canon/canon.py": "<SHA-256>"
    }
  }
}

[0027] The kernel_bundle_hash is the canonical conformance reference. It is recomputed and updated in the lockfile with every change to the Layer 0 authority file. The version label (LOCKFILE_VERSION) is incremented at each such update.

Runtime Verification

[0028] A conforming host application verifies the kernel at startup as follows:

import hashlib, pathlib, json
lockfile = json.loads(pathlib.Path("GENOME_LOCKFILE.json").read_bytes())
actual = hashlib.sha256(pathlib.Path("kernel/canon/canon.py").read_bytes()).hexdigest()
expected = lockfile["layer_0_locks"]["kernel_bundle_hash"]
assert actual == expected, f"Kernel integrity check failed: {actual!r} != {expected!r}"

[0029] Any modification to the Layer 0 authority file — accidental or deliberate — produces a hash mismatch detectable before any canonical computation is performed. This is the runtime verifiability guarantee.

Downstream Hash Re-Export

[0030] Downstream repositories record their expected kernel hash in their own GENOME_LOCKFILE.json:

{ "pinned_kernel_hash": "<same SHA-256 as SDK kernel_bundle_hash>" }

[0031] When a downstream consumer imports the kernel, it can compare the installed hash against its own pin without querying any external service. A mismatch indicates either an unintended kernel upgrade or a tampered installation.

Claims Summary

[0032] The following novel aspects of the architecture are asserted as prior art:

1. A two-layer software distribution architecture for a cryptographic protocol kernel wherein a designated Layer 0 authority file is the exclusive location of all canonical logic, and a Layer 1 shim file loads the authority file at import time via an absolute path derived from __file__ using importlib.util.spec_from_file_location, independent of sys.path.

2. A GENOME_LOCKFILE.json record binding the SHA-256 hash of a Layer 0 authority file to a versioned protocol conformance claim, enabling runtime verification that the installed implementation is byte-identical to the declared reference.

3. A hash re-export pattern wherein downstream repositories independently record their expected kernel_bundle_hash, enabling version-skew detection without querying a package registry.

4. A single-source rule enforced by a test suite that imports from both Layer 0 and Layer 1 paths and asserts identical outputs, detecting any unauthorised duplication of canonical logic.

Related Specifications