Metadata-Version: 2.4
Name: hive-hub
Version: 0.1.1
Summary: Protocol-neutral, local-first Hive discovery and bootstrap core
Author: Hive Hub contributors
License-Expression: MIT
Keywords: hive,protocol,discovery,local-first
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Hive Hub

Hive Hub 0.1.1 is one protocol-neutral release containing a typed Python core,
optional stdlib adapters, a universal Agent Skill, and a deterministic static
API/Pages surface. The distribution imports as `hive_hub`, includes the
separately importable `adapters` package, and installs the `hive-hub` command.

Importing the core does not import or require an adapter, RAPP tool, GitHub
client, or network runtime. A Hive declares its exact protocol fingerprint,
content-addressed learning bundle, conformance contract, and inert adapter
registration. Chants, URLs, QR codes, repositories, and static APIs are
locators—not authority.

## Guarantees

- Canonical UTF-8 JSON and `urn:hivehub:sha256:<64hex>` content addresses.
- Closed contracts: unknown keys, duplicate JSON keys, floats, and oversized
  inputs are rejected.
- Physically separate local, public, and private dialbooks.
- The public index builder opens only `<home>/books/public`; it cannot read or
  hash the private book.
- Collision-preserving chant and URL candidate arrays.
- Protocol-neutral `hive-hub-chant/1` derivation from the UTF-8 full Dial
  Record ID. Canonical records carry exactly one derived seven-word chant;
  the complete ID must still verify.
- Plan-first local subscriptions. Clone, authentication, fetch, write, and
  execution effects remain explicit inert adapter plans requiring approval.
- Existing source ACLs remain mandatory for private access.
- Private absence, failed ACL, missing policy, and wrong optional QR factor all
  return the identical `unreachable` result.
- No-follow reads, bounded traversal, regular-file checks, atomic no-replace
  writes, reversible subscription writes, and per-record interprocess
  transactions for private record/policy registration.
- Locked skill files reject symlinks, special files, and real hardlinks.
  Windows verification reads the true link count from a no-follow Win32 file
  handle; every platform requires exactly one link, and byte counts and SHA-256
  hashes must still match exactly.
- No downloaded protocol text, skill, or adapter is executed.
- The universal skill never executes repository-provided setup or verification
  code. Joining saves a subscription and returns an inert typed adapter plan;
  execution is reserved for separately approved locally shipped immutable code
  pinned by local trust.
- Built-in adapter contracts are loaded lazily; unavailable RAPP tooling remains
  inert and never becomes a core requirement.

## Install

```bash
python -m pip install hive-hub
hive-hub --help
```

Python 3.10, 3.11, and 3.14 are release-gated. Runtime dependencies are empty.

## CLI

These work immediately after `pip install hive-hub`, with no files and no
network:

```bash
hive-hub chant derive \
  dial:sha256:6b822d070281ee28b89c3c4209e5ba6e796a09ec5973da6e73324cee44127c32
hive-hub chant parse "JUNIPER QUARTZ HARBOR BIRCH COBALT NOOK FLINT"
hive-hub schema list
hive-hub status
```

That Dial Record ID is the live public laboratory Hive in the
[public dialbook](https://kody-w.github.io/hive-hub/api/hive-hub/v1/dialbook.json),
and it derives exactly that chant. A chant is a locator, not authority; the
complete Dial Record ID must still verify.

The rest of the walkthrough uses the example contracts, which ship in the
source tree rather than the wheel:

```bash
git clone https://github.com/kody-w/hive-hub && cd hive-hub
export HIVE_HUB_HOME="$PWD/.hive-hub"

hive-hub validate examples/generic/protocol-declaration.json
hive-hub learn \
  examples/generic/protocol-declaration.json \
  examples/generic/learning-bundle.json
hive-hub adapter register examples/generic/adapter-registration.json
hive-hub register public examples/generic/public-dial-record.json

hive-hub dial "VINE TRENCH SABLE OXBOW ATLAS ATLAS ESTER" --scope public
hive-hub inspect "$(python - <<'PY'
import json
print(json.load(open("examples/generic/manifest.json"))["protocol_fingerprint"])
PY
)"
hive-hub subscribe plan examples/generic/ai-join-card.json
hive-hub bootstrap examples/generic/ai-join-card.json --apply
hive-hub status
hive-hub adapter builtin list
hive-hub adapter builtin show github-repository
```

Installing built-in adapter contracts is plan-first. The first command returns
an exact plan id; repeat with `--apply <plan-id>` to store only inert local
contracts and a receipt. It does not execute the adapter.

Every success and failure is one JSON object. Failures use
`{"ok":false,"error":{"code":"...","message":"..."}}` without a traceback or
echoing private input.

Other commands:

```text
hive-hub register local|public|private RECORD
hive-hub dial QUERY [--scope auto|local|public|private]
hive-hub join-card --principal-kind human|ai --principal-id ID --locator QUERY
hive-hub subscribe plan CARD
hive-hub subscribe apply PLAN
hive-hub subscribe revert PLAN
hive-hub index public|private
hive-hub schema list
hive-hub schema show CONTRACT
```

## Python API

```python
from hive_hub import HiveHub, Principal, derive_chant

hub = HiveHub("state")
chant = derive_chant(
    "urn:hivehub:sha256:"
    "de1124a60f97f732ebd13fba183bcd109e4a506620a64e591e2bfc61c962b752"
)
result = hub.dial(chant, scope="public")
card = hub.create_join_card(
    principal=Principal.create(kind="ai", identifier="agent:example"),
    locator=result.record.id,
)
planned = hub.plan_local_subscription(card)
applied = hub.apply_subscription(planned.plan)
```

`derive_chant`, `normalize_chant`, `verify_chant`, `learn_protocol`,
`register_adapter`, `register_local_record`,
`register_public_record`, `register_private_record`, `dial`,
`create_join_card`, `plan_local_subscription`, `apply_subscription`,
`revert_subscription`, `inspect_protocol`, and `bootstrap_one` are the main
core APIs. `inspect_bundle` returns the complete inert learning bundle and
artifact text without importing or executing it.

## Private access

`acl-only` is the default. The core accepts an `acl_authorized=True` result only
after an external adapter has applied the source's existing ACL. It never adds
collaborators or brokers credentials.

Optional `acl+qr` adds a second factor after ACL:

- the factor is exactly 256 random bits encoded as unpadded base64url;
- its commitment is domain-separated and bound to record id, scope, and epoch;
- comparison uses `hmac.compare_digest`;
- only the commitment is stored, only in the private policy;
- the fragment is supplied transiently (CLI: `--qr-fragment-stdin`);
- the fragment is forbidden in records, indexes, cards, plans, receipts, and
  locators. Browser integrations must keep it out of persisted browser storage.

Locator-only QR remains the recommended default.

## Documentation

- [Contract and addressing reference](docs/CONTRACTS.md)
- [CLI and storage layout](docs/CLI.md)
- [Security model](docs/SECURITY.md)
- [0.1.1 release inventory](RELEASE_INVENTORY.md)
- [Deterministic release manifest](release/release-manifest.json)
- [Generic non-RAPP example](examples/README.md)

## Neutral adapter package

`adapters/` is a stdlib-only, typed source tree that can be merged into the
core package without importing any RAPP runtime:

| Adapter | Exact protocol |
|---|---|
| GitHub repository locator/probe | `hive-hub-github-repository/1.0` |
| Local filesystem workspace | `hive-hub-local-workspace/1.0` |
| Installed RAPP Work/Hive delegate | `hive-hub-rapp-delegate/1.0` |
| Legacy RAPPID summon-chant compatibility | `rappidex/1-summon-chant` |
| Payphone DoorRef/dial result | `rapp-payphone-dial/1.0` |
| Historical Hub inspector | `legacy-rapp-hub/00ac2f73` |

Each declaration binds its protocol to canonical contract bytes with SHA-256
and includes capability requirements, supported private-access modes, an inert
learning bundle, and local conformance fixtures. The registry performs exact
fingerprint lookup only. An unknown fingerprint returns an inert adapter and
is never routed to RAPP.

The GitHub probe uses `git ls-remote` with caller-owned ambient credentials,
stdin closed, and interactive prompts disabled. Every nonzero response is the
same `unreachable` result, so an absent repository cannot be distinguished
from one the caller cannot access. It never changes repository ACLs or remote
state.

The generic core owns `hive-hub-chant/1`. It hashes the UTF-8 full canonical
Dial Record ID with SHA-256 and maps the first seven digest bytes modulo the
frozen 128-word vocabulary. Human input accepts case differences and spaces;
canonical output is exactly seven lowercase hyphen-separated words. The
vocabulary is reused byte-for-byte from
`kody-w/rappid@c988d7975dadb6a8f055183cdbc4cbb17adfe2ae`, with hash
`325f47d38851721f16cf111f80114d8d9146e84813fa6822fe2ad38dd18dbb36`,
but the generic derivation requires no RAPP identity, adapter, or runtime.
Chants remain collisionable 49-bit candidate locators, and candidate selection
must verify the complete Dial Record ID.

The optional RAPPID adapter retains its separate compatibility derivation over
a full RAPPID. Payphone routing prefixes likewise never authorize: connection
requires the exact full RAPPID.

## Conformance

```sh
python3 -m unittest discover -s adapters/tests -v
ruff check adapters
mypy --strict adapters
```

Fixtures cover canonical GitHub forms, absent/unauthorized indistinguishability,
ambient-token hygiene, no remote writes, exact chant vectors and collision
buckets, new Payphone DoorRef vectors and truncated-ID collisions, and inert
historical malicious instructions.

## Explicit compatibility refusals

- The installed legacy `rapp` Rapid AI Agent Production Pipeline CLI is not a
  RAPP Work/Hive authority delegate. Only `rapp-work` and `rapp-hive` adapter
  entry points are considered.
- The historical RAPPidex “first repository wins” behavior is incompatible
  with collision-safe lookup and is not used.
- Legacy/provisional RAPPID forms are inspection or migration evidence, not
  active chant or Payphone inputs. Active parsing requires the exact lowercase
  RAPP/1 form with a 64-hex tail.
- Historical Payphone Issues/PR mutation rungs and the `no-answer` outcome are
  outside this neutral read-only adapter. Its result is only `connected` or
  `unreachable`.
- `RAPP_Hub@00ac2f73` server, Docker, skill, and instruction surfaces are never
  downloaded, installed, imported, or executed. The adapter reads bounded
  already-local JSON only.

## Static network

Hive Hub is a deterministic, no-server discovery surface that is equally usable
by humans and AI clients. The generic core does not assume one Hive protocol,
host, runtime, or authority model.

The committed public surface is:

- `/.well-known/hive-hub.json`
- `/llms.txt`
- `/api/hive-hub/v1/`
- `/api/hive-hub/v1/core-schemas/`
- `/api/hive-hub/v1/release.json`
- `/hub/`
- `/hub/join/`

Those paths work as ordinary GitHub Pages files and as raw Git repository files.
The Pages workflow publishes only the generated surface, not the build tools or
source documents.

## Safety model

- Chants, URLs, Git references, cards, and QR codes are candidate locators only.
- A chant always maps to an array of candidates and never establishes unique
  authority.
- Display/search aliases are indexed separately and are never accepted as
  chants.
- Every Dial Record binds an exact protocol declaration, learning bundle,
  conformance contract, and adapter by canonical JSON SHA-256.
- Downloaded code, protocol text, skills, and adapters remain inert until
  independently approved and verified.
- Existing source ACLs remain authoritative. The Hub adds no collaborator,
  credential, broker, or private-target oracle.
- The public example claims neither authority nor semantic compatibility.

## Static API

`api/hive-hub/v1/index.json` links the public dialbook, four deterministic
SHA-256 record buckets, federation indexes, content-addressed objects, schemas,
cards, status, hashes, offline seed, and append-only receipt ledger.

Immutable JSON uses canonical UTF-8 bytes with sorted object keys and one final
line feed. Its reference is `sha256:<digest>`, and its path ends in that digest.
Mutable discovery indexes contain hashes for the immutable objects they name.
`hashes.json` covers every generated public file except itself, avoiding a
recursive self-hash.

Federation unions candidate dialbooks and bucket indexes. It does not promote
any peer, chant, or record into authority.

The public onboarding laboratory points only to Hive Hub's minimal founding
revision. Its full Dial Record ID is
`dial:sha256:6b822d070281ee28b89c3c4209e5ba6e796a09ec5973da6e73324cee44127c32`
and its derived chant is `juniper-quartz-harbor-birch-cobalt-nook-flint`.
`hive-hub-public-lab` is only a display/search alias. This demonstrates discovery
and a reversible local subscription, not a running autonomous service.

Private and unlisted Hives are dark doors: their names, addresses, chants, QR
codes, records, and learning metadata must not enter the public projection.
Share their locators through already-authorized private channels; the source
ACL remains authoritative. A repository being readable is not permission to
advertise it.

Public receipt history is append-only unless a maintainer explicitly retires
an exact prior manifest digest in `public-withdrawals.json`. That exceptional
privacy withdrawal requires the old receipt sources and generated receipt
URLs to be absent, not rewritten at their old content addresses. It does not
erase Git history, existing downloads, or third-party caches.

## Ten public RAPP Work organization seeds

The [Hub catalog](https://kody-w.github.io/hive-hub/hub/#organizations) contains
ten real, downloadable starter packages: a One-Person Conglomerate, Enterprise
Transformation Firm, Product Launch Company, Open-Source Infrastructure
Foundation, Applied Invention Lab, Independent Game Studio, Micro-Manufacturing
Company, Public-Source Intelligence Bureau, Turnaround Firm, and Federation
Prime Contractor.

Each has scoped team workspaces, an original synthetic intake case, a task DAG
with ownership and acceptance criteria, usable starter artifacts, an exact file
inventory, a deterministic ZIP, and its own verified join card and QR. They
replace the prompt-only showcase. The protocol-only public laboratory remains
addressable separately.

The seeds use the exact canonical `rapp-work-sdk/1` SDK. Organizations are
pointer-only; team content and shared casework remain in distinct same-world
workspaces. A consumer selects its owner and destination and approves complete
native plans before initialization. The catalog does not claim activated
companies, running agents, private membership, completed work, or signed estate
authority.

The generic Hub core remains protocol-neutral. Seed data is an optional public
example layer, not a replacement RAPP runtime. See
[the package and initialization guide](docs/ORGANIZATION_SEEDS.md).

The [standalone global skill](skills/hive-network/SKILL.md) is one file a person
can give to their existing AI. It guides local use and reviewed contributions
without installing a daemon, copying provider stores, granting access, or
mistaking a subscription for an activated organization.

## Explicit public-only build

The build command requires an explicit `public-manifest.json`:

```console
npm ci --ignore-scripts
npm run build
```

The manifest must:

1. declare `classification: "public-only"`;
2. use exactly `sourceRoot: "public-src"`;
3. list every input file individually as `classification: "public"`;
4. pin every input's exact SHA-256; and
5. define complete, non-overlapping record buckets.

The public reader performs no directory discovery. It opens only the manifest
and its allowlisted, pinned files, rejects symlinks and path traversal, and
records the complete read set in `hashes.json`. Tests place an unreadable
private-book sentinel next to an allowed public root and prove it is never
inspected. A traversal entry is rejected before file access.

After intentionally editing a public input, refresh its explicit pin:

```console
npm run pin:public
npm run verify
```

## QR join cards

Public QR SVGs are generated at build time with the exact build-only dependency
in `package-lock.json`. Their fragment contains only:

```json
{"card":"<same-origin content-addressed card URL>","sha256":"<digest>","v":1}
```

`/hub/join/` captures that fragment and immediately removes it with
`history.replaceState` before fetching anything. It then fetches same-origin
static JSON, verifies the card, Dial Record, protocol, learning bundle, adapter,
and conformance contract, and cross-checks `hashes.json`.

Humans receive accessible steps. AI clients can use `?format=json`,
`?format=llms`, `/hub/join/ai.json`, or `/llms.txt`. The browser runtime has no
external scripts, analytics, service workers, persistent storage, telemetry, or
credentialed requests. CSP and no-referrer policies are embedded in each page.

Sensitive locator-plus-unlock cards are a separate local-only tool. It permits
output only under ignored `.hive-hub/private-cards/` or `tests/.work/` paths:

```console
node scripts/generate-sensitive-card.mjs \
  --input .hive-hub/local-card.json \
  --out-dir .hive-hub/private-cards/example
```

Local card input must declare `accessMode: "acl+qr"` and provide a canonical
unpadded base64url encoding of exactly 32 random bytes. The generated JSON is
the exact closed shape accepted by the skill:

```json
{"locator":"<validated skill locator>","schema":"hive-hub-qr-join-card/1","unlock_fragment":"<43-character factor>"}
```

The source ACL must succeed first; the QR value is only a second factor and
cannot replace or weaken source authorization.

The public builder never imports or invokes that tool, and public-card
validation rejects sensitive fields.

## Receipts

Receipt source entries are ordered and immutable. Generated receipts are
content-addressed, each receipt links its predecessor, and the ledger head is
published at `api/hive-hub/v1/receipts/index.json`.

Compare a change against an existing branch:

```console
npm run check:receipts -- --base main
```

This rejects removed, reordered, modified, or replaced historical receipt
sources and published receipt objects. Corrections are new receipts rather than
edits.

## Gates

```console
npm run verify
```

The gate rebuilds, validates canonical JSON, links, hashes, content-addressed
paths, bucket coverage, federation candidate arrays, receipt chains, QR SVGs,
runtime restrictions, CSP/referrer metadata, basic accessibility, public-input
isolation, exact example revision, and byte-for-byte reproducibility.

## Universal Agent Skill

`skills/hive-hub/` is a complete Agent Skill for a person or any AI. It accepts
the core `ai-join-card` contract used by the generated camera-AI card as well
as its compact locator-card formats. Copy that folder into a tool's skills
directory and ask it to:

- “dial this hive”
- “join this hive on this device and tell me when you are ready”
- scan a camera/QR Hive card

It accepts a public or private GitHub URL, `owner/repo at branch`, a local path,
a `hive-hub-chant/1` seven-word chant, a full Dial Record ID, or QR/AI join-card
JSON. An optional workspace address can accompany any request. Chant candidates
are accepted only when their complete verified declaration carries the same
Dial Record ID; repository slugs are not chants.

The locked Python 3.11+ runner uses only the standard library and must run with
isolated mode:

```bash
cd skills/hive-hub
python3 -I -B scripts/run.py decode --locator 'owner/repo at branch'
python3 -I -B scripts/run.py join --locator 'owner/repo at branch'
python3 -I -B scripts/run.py join --locator 'owner/repo at branch' \
  --apply '<exact returned plan digest>'
```

Every network read and local write is planned first. Static plans bind the
canonical declaration URL, expected SHA-256, byte count, locator, and output
root identity; apply recomputes that exact plan. Trusted-origin and DNS/IP
checks reject loopback, private, link-local, reserved, metadata, and redirected
targets before static content is accepted. Existing source access is used
without prompting or credential output. Repository code is always inert.
Unknown protocols return one blocker with their content-addressed learning
bundle.

## Verify

The core, adapters, skill, generated static surface, release inventory, and
privacy boundary are checked together:

```bash
PYTHONPATH=src:. python3 -B -m unittest \
  tests.test_contracts tests.test_hub tests.test_private_access \
  tests.test_safety_cli tests.test_adapter_runtime -v
python3 -B -m unittest discover -s adapters/tests -t . -v
python3 -B -m unittest tests.test_hive_hub -v
python3 scripts/check.py
python3 scripts/prove.py
npm ci --ignore-scripts
npm run verify
python3 scripts/check_public_release.py
python3 scripts/build_release_manifest.py --check
```

`prove.py` also copies the skill to a path with spaces and verifies that the
copied folder operates without repository context.
