diff --git a/docs/architecture/verse-service-contract.md b/docs/architecture/verse-service-contract.md index 57a0c2d..b84ed11 100644 --- a/docs/architecture/verse-service-contract.md +++ b/docs/architecture/verse-service-contract.md @@ -49,6 +49,10 @@ Ghostlight already has these substrate pieces: state; - architecture docs for persistence, projection, training loops, prompt projection, and shared Persona/CultNet contracts. +- `tools/ghostlight_state.py publish-odin` and + `tools/publish_odin_provider_advertisement.cjs` publish Ghostlight's + provider advertisement once to Odin's CultMesh/RUDP document ingress when an + endpoint is supplied. The missing surface is not another readable export. The missing surface is a provider-owned Eve GUI/TUI composition over the existing state and review seams. @@ -79,7 +83,7 @@ not the canonical owner. 2. Define a `ghostlight.eve_surface.v0` provider contract over the current state, projection, review, and Persona documents. 3. Add a read-only command that lowers those documents into Eve DSL. -4. Publish the surface through CultMesh/Odin discovery. +4. Publish the provider advertisement through CultMesh/Odin discovery. 5. Let browser/native/TUI runtimes lower the same surface. 6. Demote old preview/status dashboards to renderers of the provider-owned Eve surface. diff --git a/package.json b/package.json index 49abf2f..4b10e9a 100644 --- a/package.json +++ b/package.json @@ -6,6 +6,7 @@ "scripts": { "state:status": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\ghostlight_state.py status", "provider:advertisement": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\ghostlight_state.py provider-advertisement", + "provider:publish-odin": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\ghostlight_state.py publish-odin", "state:prepare-compaction": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\ghostlight_prepare_compaction.py", "agent-state:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_agent_state.py", "persona-state:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_persona_state.py", diff --git a/tools/ghostlight_state.py b/tools/ghostlight_state.py index 8809783..3203764 100644 --- a/tools/ghostlight_state.py +++ b/tools/ghostlight_state.py @@ -2,6 +2,9 @@ from __future__ import annotations import argparse import json +import os +import subprocess +import sys from datetime import datetime, timezone from pathlib import Path from typing import Any @@ -18,6 +21,17 @@ COVERAGE_PATH = STATE_DIR / "corpus-coverage.json" PROVIDER_ADVERTISEMENT_FIXTURE_PATH = ( ROOT / "examples" / "ghostlight-provider-advertisement.v0.json" ) +ODIN_PROVIDER_PUBLISHER_PATH = ROOT / "tools" / "publish_odin_provider_advertisement.cjs" +DEFAULT_NODE_PATH = ( + Path.home() + / ".cache" + / "codex-runtimes" + / "codex-primary-runtime" + / "dependencies" + / "node" + / "bin" + / ("node.exe" if os.name == "nt" else "node") +) def read_text(path: Path) -> str: @@ -89,6 +103,29 @@ def cmd_provider_advertisement(args: argparse.Namespace) -> int: return 0 +def cmd_publish_odin(args: argparse.Namespace) -> int: + endpoint = args.odin_cultmesh_rudp or os.environ.get("GHOSTLIGHT_ODIN_CULTMESH_RUDP", "") + if not endpoint: + raise SystemExit( + "Missing Odin endpoint. Pass --odin-cultmesh-rudp host:port or set GHOSTLIGHT_ODIN_CULTMESH_RUDP." + ) + + node = Path(args.node or os.environ.get("NODE", "") or DEFAULT_NODE_PATH) + if not node.exists(): + raise SystemExit(f"Node runtime not found: {node}") + + command = [ + str(node), + str(ODIN_PROVIDER_PUBLISHER_PATH), + "--odin-cultmesh-rudp", + endpoint, + "--fixture", + str(PROVIDER_ADVERTISEMENT_FIXTURE_PATH.relative_to(ROOT)), + ] + result = subprocess.run(command, cwd=ROOT, text=True) + return result.returncode + + def cmd_status(_: argparse.Namespace) -> int: branches = load_branches().get("branches", []) active = [branch for branch in branches if branch.get("status") == "active"] @@ -176,6 +213,21 @@ def build_parser() -> argparse.ArgumentParser: ) provider_parser.set_defaults(func=cmd_provider_advertisement) + publish_odin_parser = subparsers.add_parser( + "publish-odin", + help="Publish Ghostlight's provider advertisement once to Odin over CultMesh/RUDP.", + ) + publish_odin_parser.add_argument( + "--odin-cultmesh-rudp", + dest="odin_cultmesh_rudp", + help="Odin CultMesh/RUDP document ingress endpoint as host:port.", + ) + publish_odin_parser.add_argument( + "--node", + help="Node executable to use for the CultMesh runtime publisher.", + ) + publish_odin_parser.set_defaults(func=cmd_publish_odin) + evidence_parser = subparsers.add_parser( "add-evidence", help="Append one distilled JSONL evidence record." ) diff --git a/tools/publish_odin_provider_advertisement.cjs b/tools/publish_odin_provider_advertisement.cjs new file mode 100644 index 0000000..f982e3a --- /dev/null +++ b/tools/publish_odin_provider_advertisement.cjs @@ -0,0 +1,175 @@ +#!/usr/bin/env node +"use strict"; + +const fs = require("node:fs"); +const Module = require("node:module"); +const path = require("node:path"); + +const repoRoot = path.resolve(__dirname, ".."); +process.env.NODE_PATH = [ + path.resolve(repoRoot, "..", "CultLib", "packages"), + process.env.NODE_PATH || "", +].filter(Boolean).join(path.delimiter); +Module._initPaths(); + +const { defineDocumentType } = require("cultcache-ts"); +const { CultMesh } = require("cultmesh-ts"); +const { defineCultNetDocumentBinding } = require("cultnet-ts"); + +const providerAdvertisementDefinition = defineDocumentType({ + type: "gamecult.eve.provider_advertisement", + schemaName: "gamecult.eve.provider_advertisement", + schemaId: "gamecult.eve.provider_advertisement.v1", + schemaVersion: "gamecult.eve.provider_advertisement.v1", + global: true, + name: (value) => value?.providerId || "ghostlight", + schema: { parse: (value) => value }, + members: [ + { slot: 0, memberName: "providerId", typeName: "string", isName: true }, + { slot: 1, memberName: "serviceId", typeName: "string" }, + { slot: 2, memberName: "verseId", typeName: "string" }, + { slot: 3, memberName: "title", typeName: "string" }, + { slot: 4, memberName: "description", typeName: "string" }, + { slot: 5, memberName: "canonicalService", typeName: "string" }, + { slot: 6, memberName: "locatedService", typeName: "string" }, + { slot: 7, memberName: "cultMeshAddress", typeName: "string" }, + { slot: 8, memberName: "status", typeName: "string" }, + { slot: 9, memberName: "updatedAt", typeName: "string" }, + { slot: 10, memberName: "capabilities", typeName: "array" }, + { slot: 11, memberName: "endpoints", typeName: "array" }, + { slot: 12, memberName: "routes", typeName: "array" }, + ], +}); + +main().catch((error) => { + console.error(error?.stack || error?.message || String(error)); + process.exitCode = 1; +}); + +async function main() { + const args = parseArgs(process.argv.slice(2)); + const endpoint = args["odin-cultmesh-rudp"] || process.env.GHOSTLIGHT_ODIN_CULTMESH_RUDP || ""; + if (!endpoint) { + throw new Error("Ghostlight Odin publication requires --odin-cultmesh-rudp or GHOSTLIGHT_ODIN_CULTMESH_RUDP."); + } + + const fixturePath = path.resolve(repoRoot, args.fixture || "examples/ghostlight-provider-advertisement.v0.json"); + if (!isInside(repoRoot, fixturePath)) { + throw new Error("Ghostlight provider fixture path must stay inside the repo."); + } + + const fixture = JSON.parse(fs.readFileSync(fixturePath, "utf8")); + const advertisement = buildOdinAdvertisement(fixture, fixturePath); + await CultMesh.publishRudpDocumentOnce( + "ghostlight", + 0x0d1d0002, + normalizeRudpEndpoint(endpoint), + defineCultNetDocumentBinding({ definition: providerAdvertisementDefinition }), + advertisement.providerId, + advertisement, + { + sourceRole: "ghostlight.provider", + tags: ["startup-respect", "odin-verse-discovery"], + }, + ); + + console.log(JSON.stringify({ + ok: true, + schemaId: "gamecult.eve.provider_advertisement.v1", + providerId: advertisement.providerId, + odinCultMeshRudp: endpoint, + }, null, 2)); +} + +function buildOdinAdvertisement(fixture, fixturePath) { + const observedAt = new Date().toISOString(); + const providerId = fixture.provider_id || "ghostlight"; + const surfaces = Array.isArray(fixture.eve_surfaces) ? fixture.eve_surfaces : []; + const schemas = Array.isArray(fixture.schemas) ? fixture.schemas : []; + const witnesses = Array.isArray(fixture.cultcache_witnesses) ? fixture.cultcache_witnesses : []; + return { + providerId, + serviceId: "ghostlight.social-agent-state", + verseId: "starfire.local", + title: fixture.service_name || "Ghostlight", + description: "Socially persistent generative-agent state/projection research service candidate.", + canonicalService: "asgard.ghostlight", + locatedService: "asgard.starfire.ghostlight", + cultMeshAddress: "asgard.starfire.ghostlight/state", + status: "read-only-provider-advertisement", + updatedAt: observedAt, + capabilities: [ + "social-agent-state", + "persona-state-projection", + "training-fixture-review", + "cultcache-witness", + "eve-surface-target", + ], + endpoints: [ + { transport: "cultcache-witness", address: "state/ghostlight-state.cultcache.jsonl" }, + { transport: "repo-fixture", address: path.relative(repoRoot, fixturePath).replace(/\\/g, "/") }, + ], + routes: [ + { transport: "repo-cli", address: "npm run provider:advertisement", role: "provider-advertisement" }, + { transport: "repo-cli", address: "npm run state:status", role: "status" }, + ], + schemaCatalog: schemas.map((schema) => ({ + schemaId: schema.schema_version || schema.document_type || "unknown", + path: schema.path || "", + owns: Array.isArray(schema.owns) ? schema.owns : [], + })), + witnessCatalog: witnesses.map((witness) => ({ + schemaId: witness.document_type || "unknown", + path: witness.witness_path || "", + readableExport: witness.readable_export || "", + authority: witness.authority || "", + })), + surfaces: surfaces.map((surface) => ({ + id: surface.surface_id || "ghostlight.surface", + title: surface.title || surface.surface_id || "Ghostlight Surface", + panels: Array.isArray(surface.panels) ? surface.panels : [], + })), + commandSurface: { + mode: "read-only", + commands: ["status", "provider-advertisement", "publish-odin"], + mutationPolicy: "reviewed mutation intent only", + }, + authority: fixture.authority || {}, + ghostlightProviderAdvertisement: fixture, + }; +} + +function normalizeRudpEndpoint(value) { + const text = String(value || "").trim(); + if (!text) throw new Error("Odin CultMesh/RUDP endpoint must be non-empty."); + if (text.startsWith("rudp://")) return text; + const ipv6 = text.match(/^\[([^\]]+)\]:(\d+)$/); + if (ipv6) return `rudp://[${ipv6[1]}]:${ipv6[2]}`; + const index = text.lastIndexOf(":"); + if (index <= 0 || index === text.length - 1) { + throw new Error(`Odin CultMesh/RUDP endpoint must be host:port, got "${value}".`); + } + return `rudp://${text.slice(0, index)}:${text.slice(index + 1)}`; +} + +function parseArgs(argv) { + const parsed = {}; + for (let index = 0; index < argv.length; index += 1) { + const arg = argv[index]; + if (!arg.startsWith("--")) continue; + const key = arg.slice(2); + const next = argv[index + 1]; + if (!next || next.startsWith("--")) { + parsed[key] = true; + } else { + parsed[key] = next; + index += 1; + } + } + return parsed; +} + +function isInside(root, candidate) { + const relative = path.relative(root, candidate); + return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); +}