Skip to content

Commit 3dcb09c

Browse files
author
mdheller
committed
Phase 0: Cybernetic Genesis schema pack (frozen contract baseline)
Ship the schema pack FIRST per the plan's Phase-0 rule: stable vocabulary and schemas before any broad adapter work. - schemas/ (JSON Schema draft 2020-12, additionalProperties:false): common (shared $defs: ContentHash, Witness/Witnesses/WitnessesDualType, Measurement, Ref), hologram, genesis_seed, twin, twin_event_envelope, artifact_record, policy_decision, adapter_descriptor. - glossary.md: frozen Phase-0 vocabulary. - examples/: valid sample objects + 3 invalid fixtures (missing 2nd witness, bad boundary-stone hash, Twin READY without policy refs) that MUST reject. - tools/validate.py: jsonschema validator + selftest (teeth both ways, fail-closed). - docs/L0-genesis-covenant.md: source-canon doctrine (dual witness / boundary stones / weights & measures / plumb-line / never-weaponize), verse->rule table marked doctrinal source, not executable scripture. - .github/workflows/ci.yml: pip install jsonschema, run selftest. - README.md: repo purpose, 7-phase plan, L0 covenant, contract baseline. - LICENSE: MIT (c) 2026 SocioProphet. Selftest: 8 valids validate, 3 invalids rejected, exit 0.
0 parents  commit 3dcb09c

26 files changed

Lines changed: 1113 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: schema-pack-ci
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
selftest:
11+
name: schema selftest (valids validate, invalids rejected)
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout
15+
uses: actions/checkout@v4
16+
17+
- name: Set up Python
18+
uses: actions/setup-python@v5
19+
with:
20+
python-version: "3.12"
21+
22+
- name: Install jsonschema
23+
run: pip install "jsonschema>=4.18"
24+
25+
- name: Validate all JSON parses
26+
run: |
27+
python - <<'PY'
28+
import json, sys, pathlib
29+
bad = 0
30+
for p in list(pathlib.Path("schemas").glob("*.json")) + list(pathlib.Path("examples").glob("*.json")):
31+
try:
32+
json.loads(p.read_text())
33+
except Exception as e:
34+
bad += 1
35+
print(f"PARSE FAIL {p}: {e}")
36+
sys.exit(1 if bad else 0)
37+
PY
38+
39+
- name: Run schema selftest (fail-closed)
40+
run: python tools/validate.py selftest

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
__pycache__/
2+
*.pyc

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 SocioProphet
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# cybernetic-genesis
2+
3+
Contract baseline for the **Cybernetic agentic Genesis & Inception** platform:
4+
a semantic-hologram base, Genesis seeds, and verified twins (Inception + K3 bridge),
5+
governed by the **L0 dual-witness / boundary-stone** discipline.
6+
7+
This repo is **Phase 0**: the schema pack, shipped **first**, before any broad adapter
8+
work. It is the frozen vocabulary and the JSON Schemas that everything downstream
9+
consumes. Private-first.
10+
11+
> **Phase-0 rule (from the plan):** *Build the schema pack FIRST. Do not begin broad
12+
> adapter work before the vocabulary and schemas are stable.*
13+
> **Exit criteria (met):** names stop drifting, schemas validate, example objects
14+
> compile, repo structure frozen.
15+
16+
## What's here
17+
18+
| Path | What it is |
19+
| --- | --- |
20+
| `glossary.md` | The frozen Phase-0 vocabulary. Names here are the contract. |
21+
| `schemas/common.schema.json` | Shared `$defs`: `ContentHash`, `Witness(es)`, `WitnessesDualType`, `Measurement`, `Ref`. |
22+
| `schemas/hologram.schema.json` | The semantic-hologram base object. |
23+
| `schemas/genesis_seed.schema.json` | The seed a Twin is inceived from. |
24+
| `schemas/twin.schema.json` | The runtime twin + fail-closed READY gate. |
25+
| `schemas/twin_event_envelope.schema.json` | Canonical envelope for twin events. |
26+
| `schemas/artifact_record.schema.json` | Dual-witnessed, boundary-stone-addressed outputs. |
27+
| `schemas/policy_decision.schema.json` | Fail-closed verdicts (ALLOW/DENY/REQUIRE_APPROVAL). |
28+
| `schemas/adapter_descriptor.schema.json` | Adapter contract (frozen now; built Phase 1+). |
29+
| `examples/*.valid.json` | Valid sample objects (must validate). |
30+
| `examples/*.invalid.*.json` | Fixtures that MUST be rejected (teeth). |
31+
| `tools/validate.py` | jsonschema validator + `selftest` (valids pass, invalids fail). |
32+
| `docs/L0-genesis-covenant.md` | The source-canon doctrine the schemas enforce. |
33+
| `.github/workflows/ci.yml` | Installs jsonschema, runs the selftest, fail-closed. |
34+
35+
All schemas are **JSON Schema draft 2020-12**, `additionalProperties: false`, with the
36+
L0 primitives shared from `common.schema.json`.
37+
38+
## The L0 covenant (baked in, not decoration)
39+
40+
The schemas enforce five disciplines — see `docs/L0-genesis-covenant.md` for the full
41+
doctrine and the verse→rule table (cited as *doctrinal source, not executable scripture*):
42+
43+
1. **Dual witness** — `ArtifactRecord` and world-changing `ALLOW` need ≥2 witnesses of
44+
different kind: a **chart** (signer) witness AND a **method** (validator) witness.
45+
2. **Boundary stones** — `digest` / `provenance_root` must match
46+
`^(sha256|sha3-256):[0-9a-f]{64}$`.
47+
3. **Weights & measures** — every metric declares `sample_size`, `snr` (or `"n/a"`), `units`.
48+
4. **Fail-closed verdicts** — no implicit allow; a Twin is not `READY` without
49+
identity + policy + memory refs.
50+
5. **Plumb-line** — `validate.py selftest` is the CI baseline; drift is caught at the gate.
51+
52+
## Run the checks locally
53+
54+
```bash
55+
pip install jsonschema
56+
python tools/validate.py selftest # valids validate, invalids rejected; exit 0
57+
python tools/validate.py hologram.schema.json:hologram.valid.json # one-off pair
58+
```
59+
60+
## The 7-phase plan
61+
62+
- **Phase 0 — Schema pack (SHIPPED, this repo).** Glossary + schemas + fixtures + CI.
63+
Contract baseline consumed downstream.
64+
- **Phase 1 — Adapters.** Bind providers/organs/surfaces via `AdapterDescriptor`.
65+
- **Phase 2 — Genesis.** Author holograms + seeds against the frozen schemas.
66+
- **Phase 3 — Inception + K3 bridge.** Instantiate and verify Twins (chart+method) to READY.
67+
- **Phase 4 — Missions & organs.** Run Twins under bounded organ sets; emit envelopes.
68+
- **Phase 5 — Policy plane.** Enforce fail-closed `PolicyDecision`s on world-changing acts.
69+
- **Phase 6 — Federation & provenance.** Cross-peer twins with sealed `ArtifactRecord` lineage.
70+
71+
Phases 1–6 are tracked downstream and MUST consume the contracts frozen here.
72+
73+
## License
74+
75+
MIT © 2026 SocioProphet. See `LICENSE`.

‎docs/L0-genesis-covenant.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# L0 Genesis Covenant — the source-canon discipline the schemas enforce
2+
3+
This document is the **doctrinal source** for the Phase-0 schema pack. It records *why*
4+
the schemas carry the constraints they carry. The verse references below are cited as a
5+
**source of engineering doctrine and provenance — not as executable scripture**. Nothing
6+
here runs; the enforcement lives in `schemas/*.schema.json` and `tools/validate.py`.
7+
8+
The through-line: a governed system must be **honest about what it knows, immutable about
9+
what it has recorded, and closed when unsure**. Five disciplines make that concrete.
10+
11+
## The disciplines
12+
13+
### 1. Dual witness — a matter is established by two
14+
A single attestation is not enough to make a world-changing claim true. Every
15+
`ArtifactRecord`, and every world-changing `PolicyDecision` = `ALLOW`, must carry **two
16+
witnesses of different kind**: a **chart** witness (a signer / identity attestation) AND
17+
a **method** witness (a validator / verification attestation). One signer alone, or two
18+
validators alone, does not establish the matter.
19+
Enforced by: `common.schema.json#/$defs/WitnessesDualType` (`minItems: 2` + `contains`
20+
chart + `contains` method), required on `ArtifactRecord.witnesses`.
21+
22+
### 2. Boundary stones — do not move the landmark
23+
Content-address fields are immutable boundary markers. `digest` and `provenance_root`
24+
must be real content hashes: `^(sha256|sha3-256):[0-9a-f]{64}$`. A record whose boundary
25+
stone is malformed is rejected — you cannot quietly re-draw the line later.
26+
Enforced by: `common.schema.json#/$defs/ContentHash`.
27+
28+
### 3. Weights and measures — a just weight states its terms
29+
No naked numbers. Any metric/measurement declares `sample_size`, `snr` (a number, or an
30+
explicit `"n/a"` when signal-to-noise does not apply), and `units`. A measurement that
31+
hides its sample size or units is a false balance.
32+
Enforced by: `common.schema.json#/$defs/Measurement`, used wherever metrics appear.
33+
34+
### 4. Fail-closed verdicts — absence of proof is denial
35+
The policy plane's verdict enum is `ALLOW | DENY | REQUIRE_APPROVAL`; there is no
36+
implicit allow. A `Twin` MUST NOT reach `READY` without `identity` + `policy_refs` +
37+
`memory_refs` present and non-empty — it cannot go live blind. When in doubt, the system
38+
denies or escalates.
39+
Enforced by: `twin.schema.json` (`allOf` / `if READY then required + non-empty`),
40+
`policy_decision.schema.json` (verdict enum + world-changing-ALLOW dual-witness gate).
41+
42+
### 5. Plumb-line — measure against the line, always
43+
The schemas are the plumb-line; `tools/validate.py selftest` is the act of holding every
44+
object against it in CI. Valids must validate and invalids must be rejected — teeth both
45+
ways. Drift in names or shapes is caught at the gate, not discovered in production.
46+
Enforced by: `.github/workflows/ci.yml` running the selftest on every push/PR.
47+
48+
## Never weaponize
49+
This covenant governs **restraint**, not aggression. The disciplines exist to make the
50+
platform auditable and fail-closed toward its own operators — to refuse unproven,
51+
unwitnessed, or unbounded acts. They are not to be repurposed as offensive capability,
52+
surveillance beyond declared purpose, or a pretext to bypass a human approval gate. A
53+
Twin's power is bounded by its seed, its policy envelope, and these witnesses; that
54+
boundary is the point.
55+
56+
## Verse → rule (condensed; doctrinal source, not executable scripture)
57+
58+
| Source (doctrine) | Principle | Schema rule enforced |
59+
| ------------------------ | --------------------- | --------------------------------------------------------------- |
60+
| Deut 19:15 | Two-or-three witness | `witnesses[]` `minItems: 2`, chart + method (`WitnessesDualType`) |
61+
| Deut 19:14 / Prov 22:28 | Do not move landmarks | `ContentHash` on `digest` / `provenance_root` |
62+
| Lev 19:35-36 / Prov 11:1 | Just weights & measures | `Measurement` requires `sample_size`, `snr`, `units` |
63+
| (fail-closed governance) | No implicit allow | verdict enum; `Twin` READY requires identity+policy+memory |
64+
| Amos 7:7-8 | The plumb-line | `validate.py selftest` as CI baseline |
65+
| (never-weaponize) | Restraint, not force | bounded by seed + policy envelope + witnesses |
66+
67+
The rows are a **map from doctrine to mechanism**. The mechanism is the schema; the
68+
doctrine is why. If a future change loosens a rule, it must be argued against this table.

‎examples/adapter_descriptor.valid.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"adapter_id": "adapter:tile-store.v1",
3+
"kind": "provider",
4+
"capabilities": ["read_tiles", "write_tiles", "list_tilesets"],
5+
"identity_mode": "service_account",
6+
"policy_hooks": ["policy:atlas.baseline", "policy:geo.privacy"],
7+
"audit_fields": ["actor_id", "tile", "operation", "digest"],
8+
"rollback_strategy": "snapshot_restore"
9+
}

‎examples/artifact_record.invalid.bad_boundary_stone.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"artifact_id": "artifact:atlas.tileset.bad-hash",
3+
"digest": "md5:not-a-real-boundary-stone",
4+
"kind": "tileset",
5+
"produced_by_twin": "twin:atlas-cartographer.001",
6+
"signatures": ["sig:cosign:MEUCIQ...atlas"],
7+
"witnesses": [
8+
{
9+
"role": "release-signer",
10+
"type": "chart",
11+
"hash": "sha256:ee55ff66aa11bb22cc33dd44ee55ff66aa11bb22cc33dd44ee55ff66aa11bb22"
12+
},
13+
{
14+
"role": "policy-validator",
15+
"type": "method",
16+
"hash": "sha256:ff66aa11bb22cc33dd44ee55ff66aa11bb22cc33dd44ee55ff66aa11bb22cc33"
17+
}
18+
],
19+
"provenance_root": "sha256:1122334455667788112233445566778811223344556677881122334455667788",
20+
"lineage": ["prov:tile.compose.2026-08-02"]
21+
}

‎examples/artifact_record.invalid.missing_second_witness.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"artifact_id": "artifact:atlas.tileset.bad-single-witness",
3+
"digest": "sha256:dd44ee55ff66aa11bb22cc33dd44ee55ff66aa11bb22cc33dd44ee55ff66aa11",
4+
"kind": "tileset",
5+
"produced_by_twin": "twin:atlas-cartographer.001",
6+
"signatures": ["sig:cosign:MEUCIQ...atlas"],
7+
"witnesses": [
8+
{
9+
"name": "atlas-signing-key",
10+
"role": "release-signer",
11+
"type": "chart",
12+
"hash": "sha256:ee55ff66aa11bb22cc33dd44ee55ff66aa11bb22cc33dd44ee55ff66aa11bb22"
13+
}
14+
],
15+
"provenance_root": "sha256:1122334455667788112233445566778811223344556677881122334455667788",
16+
"lineage": ["prov:tile.compose.2026-08-02"]
17+
}

‎examples/artifact_record.valid.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"artifact_id": "artifact:atlas.tileset.2026-08-02",
3+
"digest": "sha256:dd44ee55ff66aa11bb22cc33dd44ee55ff66aa11bb22cc33dd44ee55ff66aa11",
4+
"kind": "tileset",
5+
"produced_by_twin": "twin:atlas-cartographer.001",
6+
"signatures": ["sig:cosign:MEUCIQ...atlas"],
7+
"witnesses": [
8+
{
9+
"name": "atlas-signing-key",
10+
"role": "release-signer",
11+
"type": "chart",
12+
"hash": "sha256:ee55ff66aa11bb22cc33dd44ee55ff66aa11bb22cc33dd44ee55ff66aa11bb22"
13+
},
14+
{
15+
"name": "tile-consistency-validator",
16+
"role": "method-check",
17+
"type": "method",
18+
"hash": "sha256:ff66aa11bb22cc33dd44ee55ff66aa11bb22cc33dd44ee55ff66aa11bb22cc33"
19+
}
20+
],
21+
"provenance_root": "sha256:1122334455667788112233445566778811223344556677881122334455667788",
22+
"lineage": ["artifact:atlas.tileset.2026-08-01", "prov:tile.compose.2026-08-02"],
23+
"metrics": [
24+
{ "name": "tiles_written", "value": 4096, "units": "count", "sample_size": 4096, "snr": "n/a" }
25+
]
26+
}

‎examples/genesis_seed.valid.json‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"seed_id": "seed:atlas-cartographer.v1",
3+
"archetype": "cartographer",
4+
"ontology_slice": ["geo:Place", "geo:Boundary", "geo:Tile"],
5+
"goal_schema": {
6+
"objective": "maintain a verified atlas of a bounded region",
7+
"success": "tiles fresh within 24h and boundary-consistent"
8+
},
9+
"organs_allowed": ["retriever", "planner", "tile_composer"],
10+
"retrieval_profile": {
11+
"graph": true,
12+
"hybrid": true,
13+
"multimodal": true,
14+
"self_reflective": true,
15+
"recursive": false
16+
},
17+
"memory_profile": {
18+
"episodic": true,
19+
"semantic": true,
20+
"procedural": true,
21+
"provenance": true
22+
},
23+
"policy_profile": ["policy:atlas.baseline", "policy:geo.privacy"],
24+
"provider_profile": ["provider:local-embed", "provider:tile-store"],
25+
"federation_profile": { "peers": ["atlas-north", "atlas-south"], "mode": "read_replica" },
26+
"approval_profile": { "host_mutation": "require_approval" }
27+
}

0 commit comments

Comments
 (0)