Merge pull request #3 from BlackRoad-OS/codex/structure-blackroad-os-research-repo

Organize research library and schemas

README.md

@@ -1,2 +1,21 @@
 # blackroad-os-research
-Research and field codex for BlackRoad OS: math, theory, SIG, PS-SHA∞, and papers.
+
+blackroad-os-research is the research and theory hub for BlackRoad OS. It contains conceptual papers, reference mappings, schemas, and experiments that inform the architecture of agents, journaling, and orchestration.
+
+## Repository Layout
+
+- **/papers**: Conceptual writeups structured like internal papers that capture PS-SHA∞, Spiral Information Geometry (SIG), contradiction handling, finance automation, and related architectures.
+- **/library**: Structured JSON metadata catalogs for reference materials (such as external PDFs and notes) that the system depends on.
+- **/schemas**: JSON Schemas that define core conceptual structures such as PS-SHA∞ journal entries, SIG nodes, agent identity, and journal entry shapes.
+- **/experiments**: Lightweight prototype models and simulations for contradiction handling and SIG visualizations.
+- **/glossary**: Canonical definitions of key concepts and symbols for consistent usage across repos.
+
+## How this Repo is Used by Other Repos
+
+- **blackroad-os-core** uses schemas to shape domain models for journaling, agent identity, and SIG mappings.
+- **blackroad-os-operator** consumes conceptual papers for contradiction handling, PS-SHA∞ semantics, and persistent agent identity guarantees.
+- **blackroad-os-docs** links to these resources for deeper dives and supporting references in public-facing explanations.
+
+## Contributing Notes
+
+This repository prioritizes structured, text-based research artifacts. Experiments should stay lightweight and avoid heavyweight dependencies. Add TODOs where deeper math or formalization is needed.

experiments/contradiction-sim/README.md

@@ -0,0 +1,20 @@
+# Contradiction Simulator
+
+This experiment explores how multiple agents might assign trinary values (+1, 0, -1) to propositions and how conflicts could be reconciled. It is intentionally lightweight and text-based.
+
+## Goals
+
+- Surface how disagreement accumulates across agents.
+- Prototype conflict scores to flag when orchestrators should escalate.
+- Capture resolution choices that can later be journaled via PS-SHA∞.
+
+## How to Use
+
+1. Edit `model.ts` to define propositions and agents with belief vectors.
+2. Run the TypeScript model with `ts-node` or by compiling with `tsc` if you have a toolchain available.
+3. Inspect the printed conflict scores and suggested resolutions; adjust weights or strategies as desired.
+
+## Notes
+
+- No external dependencies are required beyond the TypeScript standard library.
+- This is a sandbox; it is not meant for production decision-making.

experiments/contradiction-sim/model.ts

@@ -0,0 +1,85 @@
+export type Trinary = -1 | 0 | 1;
+
+export interface PropositionBeliefs {
+  [proposition: string]: Trinary;
+}
+
+export interface Agent {
+  id: string;
+  beliefs: PropositionBeliefs;
+  weight?: number;
+}
+
+export interface ConflictResult {
+  pair: [string, string];
+  score: number;
+}
+
+const propositions = ["P1", "P2", "P3", "P4"];
+
+const agents: Agent[] = [
+  { id: "alpha", beliefs: { P1: 1, P2: 0, P3: -1, P4: 1 }, weight: 1 },
+  { id: "beta", beliefs: { P1: 1, P2: -1, P3: -1, P4: 0 }, weight: 1 },
+  { id: "gamma", beliefs: { P1: 0, P2: 1, P3: 1, P4: -1 }, weight: 1 }
+];
+
+function conflictScore(a: Agent, b: Agent, props: string[]): number {
+  const disagreements = props.reduce((score, key) => {
+    const av = a.beliefs[key] ?? 0;
+    const bv = b.beliefs[key] ?? 0;
+    return score + Math.abs(av - bv);
+  }, 0);
+  const weight = (a.weight ?? 1) + (b.weight ?? 1);
+  return disagreements * weight;
+}
+
+function pairwiseConflicts(agentList: Agent[], props: string[]): ConflictResult[] {
+  const results: ConflictResult[] = [];
+  for (let i = 0; i < agentList.length; i++) {
+    for (let j = i + 1; j < agentList.length; j++) {
+      const score = conflictScore(agentList[i], agentList[j], props);
+      results.push({ pair: [agentList[i].id, agentList[j].id], score });
+    }
+  }
+  return results.sort((a, b) => b.score - a.score);
+}
+
+function aggregateBeliefs(agentList: Agent[], props: string[]): Record<string, Trinary> {
+  const aggregate: Record<string, Trinary> = {};
+  for (const key of props) {
+    const weightedSum = agentList.reduce((sum, agent) => sum + (agent.weight ?? 1) * (agent.beliefs[key] ?? 0), 0);
+    if (weightedSum > 0) aggregate[key] = 1;
+    else if (weightedSum < 0) aggregate[key] = -1;
+    else aggregate[key] = 0;
+  }
+  return aggregate;
+}
+
+function shouldEscalate(conflicts: ConflictResult[], threshold: number): boolean {
+  return conflicts.some((entry) => entry.score >= threshold);
+}
+
+const conflicts = pairwiseConflicts(agents, propositions);
+const aggregate = aggregateBeliefs(agents, propositions);
+const escalationThreshold = 4;
+
+console.log("Pairwise conflicts:");
+for (const entry of conflicts) {
+  console.log(`${entry.pair[0]} vs ${entry.pair[1]} => score ${entry.score}`);
+}
+
+console.log("\nAggregate beliefs:");
+for (const key of propositions) {
+  console.log(`${key}: ${aggregate[key]}`);
+}
+
+if (shouldEscalate(conflicts, escalationThreshold)) {
+  console.log("\nEscalate: contradictions exceed threshold, route to orchestrator.");
+} else {
+  console.log("\nNo escalation: contradictions within acceptable bounds.");
+}
+
+console.log("\nResolution suggestion:");
+for (const key of propositions) {
+  console.log(`- ${key}: ${aggregate[key]} (log decision in PS-SHA∞ journal)`);
+}

experiments/sig-visualizations/README.md

@@ -0,0 +1,20 @@
+# SIG Visualizations (Text-Based)
+
+This experiment produces simple text renderings of factor trees and placeholder spiral coordinates. It is a starting point for mapping SIG structures without pulling in graphics dependencies.
+
+## Goals
+
+- Convert SIG-like trees into readable, indented text.
+- Experiment with assigning radial levels and angles to nodes to approximate spiral positions.
+- Provide hooks for later visualization pipelines.
+
+## How to Use
+
+1. Modify `generator.ts` to adjust sample data or coordinate strategies.
+2. Run with `ts-node` or compile with `tsc` to view text outputs.
+3. Extend the coordinate calculation to plug into downstream visualization tools.
+
+## Notes
+
+- The coordinate math is intentionally simple and can be swapped for more rigorous geometry later.
+- Outputs are console-based to remain dependency-light.

experiments/sig-visualizations/generator.ts

@@ -0,0 +1,71 @@
+interface SigNode {
+  id: string;
+  label: string;
+  factors?: string[];
+  children?: SigNode[];
+}
+
+interface PositionedNode extends SigNode {
+  angle: number;
+  radius: number;
+  depth: number;
+}
+
+const sampleTree: SigNode = {
+  id: "agent-root",
+  label: "Finance Orchestrator",
+  factors: ["mission:control", "jurisdiction:us"],
+  children: [
+    {
+      id: "capability-compliance",
+      label: "Compliance",
+      factors: ["finra", "sec", "aml"],
+      children: [
+        { id: "surveillance", label: "Surveillance", factors: ["market", "communications"] },
+        { id: "kyc", label: "KYC", factors: ["identity", "risk-scoring"] }
+      ]
+    },
+    {
+      id: "capability-revenue",
+      label: "Revenue",
+      factors: ["pricing", "sales-ops"],
+      children: [
+        { id: "pricing-engine", label: "Pricing", factors: ["elasticity", "discounts"] },
+        { id: "deal-desk", label: "Deal Desk", factors: ["approval", "margins"] }
+      ]
+    }
+  ]
+};
+
+function positionTree(node: SigNode, depth = 0, startAngle = 0, endAngle = Math.PI * 2): PositionedNode {
+  const radius = depth + 1;
+  const angle = (startAngle + endAngle) / 2;
+  const positionedChildren = (node.children ?? []).map((child, index, arr) => {
+    const segmentSize = (endAngle - startAngle) / Math.max(arr.length, 1);
+    const childStart = startAngle + index * segmentSize;
+    const childEnd = childStart + segmentSize;
+    return positionTree(child, depth + 1, childStart, childEnd);
+  });
+
+  return {
+    ...node,
+    angle,
+    radius,
+    depth,
+    children: positionedChildren
+  };
+}
+
+function renderTree(node: PositionedNode, indent = ""): void {
+  const angleDeg = (node.angle * 180) / Math.PI;
+  console.log(`${indent}- ${node.label} [r=${node.radius.toFixed(1)}, θ=${angleDeg.toFixed(1)}°]`);
+  if (node.factors?.length) {
+    console.log(`${indent}  factors: ${node.factors.join(", ")}`);
+  }
+  for (const child of node.children ?? []) {
+    renderTree(child as PositionedNode, `${indent}  `);
+  }
+}
+
+const positioned = positionTree(sampleTree);
+renderTree(positioned);

glossary/concepts.md

@@ -0,0 +1,37 @@
+# Concepts
+
+## PS-SHA∞
+A persistent, hash-chained identity and journaling construct that records every agent action or state transition. It anchors authenticity and replayability across deployments and orchestrations.
+
+## Spiral Information Geometry
+A geometric metaphor for mapping identities and knowledge onto a spiral manifold. It highlights path dependency, growth, and recurrence by positioning capabilities and factors along angular and radial dimensions.
+
+## Agent
+A bounded, task-executing entity with defined capabilities, beliefs, and identity bindings. Agents emit journal entries and can be orchestrated individually or in pods.
+
+## Capability
+A discrete skill or function an agent can execute. Capabilities can be composed, weighted, and mapped into SIG factor trees for planning and auditing.
+
+## Task
+A unit of work assigned to an agent or pod. Tasks reference capabilities, expected outcomes, and journal entries that record execution details.
+
+## Event
+A notable occurrence captured in the system, often triggering journal entries or orchestration decisions. Contradictions and policy checks emit events for review.
+
+## Journal Entry
+A PS-SHA∞-aligned record capturing `actorId`, `actionType`, `timestamp`, `payload`, and hash links to prior entries. It forms the verifiable worldline of an agent or system.
+
+## Trinary Logic
+A reasoning framework with states {+1, 0, -1} representing true, unknown, and negated values. It keeps uncertainty and conflict explicit for downstream reconciliation.
+
+## Orchestrator
+A coordination layer that routes tasks, aggregates beliefs, resolves contradictions, and enforces journaling policies across agents.
+
+## Agent Pod
+A group of agents operating as a unit for resiliency or task coverage. Pods share SIG context and may share portions of a PS-SHA∞ worldline while maintaining individual accountability.
+
+## Finance Layer
+A cluster of finance-specialized agents (close, treasury, FP&A, compliance, etc.) governed by a finance orchestrator and audited through PS-SHA∞.
+
+## Contradiction Quarantine
+A pattern where conflicting outputs are isolated, journaled, and held for mediation before actions are taken. This prevents silent failure and preserves evidence for audit.

glossary/symbols.md

@@ -0,0 +1,13 @@
+# Symbols
+
+| Symbol | Meaning | Notes |
+| ------ | ------- | ----- |
+| `K(t)` | Knowledge state of an agent or system at time `t` | Derived from accumulated PS-SHA∞ journal entries. |
+| `C(t)` | Contradiction count or complexity score at time `t` | Increases when trinary conflicts emerge; used for escalation thresholds. |
+| `λ` | Sensitivity factor | Tunes how quickly contradictions trigger escalation or quarantine. |
+| `θ` | Spiral angular coordinate | Locates a factor or agent on the SIG manifold. |
+| `r` | Spiral radial coordinate | Represents maturity or energy of a factor in SIG. |
+| `σ` | Capability strength score | Weighted confidence of an agent's ability to execute a capability. |
+| `J` | Journal chain identifier | Associates entries to a PS-SHA∞ worldline for reconstruction. |
+| `Φ` | Resolution operator | Chosen reconciliation strategy for contradictions (e.g., majority, priority). |
+| `Δt` | Time delta between entries | Used to analyze cadence or drift in agent behavior. |

library/pdfs.json

@@ -0,0 +1,93 @@
+[
+  {
+    "id": "finra-annual-reg-oversight-2025",
+    "title": "2025 FINRA Annual Regulatory Oversight Report",
+    "author": "FINRA",
+    "year": 2025,
+    "path": "TODO/pdfs/finra-2025-annual-regulatory-oversight-report.pdf",
+    "tags": ["regulation", "finra", "compliance", "financial-crime"],
+    "summary": "High-level overview of FINRA's supervisory focus areas, including AML, cybersecurity, third-party risk, CAT, best execution, extended hours trading, and more.",
+    "usage": [
+      "Reference for compliance agents in blackroad-os-operator",
+      "Source for regulated-overview docs in blackroad-os-docs"
+    ]
+  },
+  {
+    "id": "cryptology-fundamentals-van-tilborg",
+    "title": "Fundamentals of Cryptology",
+    "author": "Henk C. A. van Tilborg",
+    "year": 2000,
+    "path": "TODO/pdfs/cryptology-fundamentals-van-tilborg.pdf",
+    "tags": ["cryptography", "crypto", "math", "security"],
+    "summary": "Comprehensive overview of classical and modern cryptosystems, including symmetric and public-key schemes, hash functions, MACs, and zero-knowledge proofs.",
+    "usage": [
+      "Reference for PS-SHA∞ and RoadChain crypto primitives",
+      "Foundation for agent identity and journaling guarantees"
+    ]
+  },
+  {
+    "id": "plan-finally-owners-manual",
+    "title": "PLAN? FINALLY? Owner's Manual",
+    "author": "BlackRoad",
+    "year": 2024,
+    "path": "TODO/pdfs/plan-finally-owners-manual.pdf",
+    "tags": ["operations", "meta", "strategy", "identity"],
+    "summary": "Internal owner's manual that encodes governance expectations, journaling norms, and worldview assumptions for agents and operators.",
+    "usage": [
+      "Sets behavioral constraints for agent identity persistence",
+      "Source material for PS-SHA∞ journaling expectations"
+    ]
+  },
+  {
+    "id": "principles-corporate-finance-brealey",
+    "title": "Principles of Corporate Finance",
+    "author": "Richard A. Brealey et al.",
+    "year": 2020,
+    "path": "TODO/pdfs/principles-of-corporate-finance.pdf",
+    "tags": ["finance", "valuation", "capital-markets"],
+    "summary": "Canonical reference on valuation, capital structure, risk management, and capital budgeting frameworks.",
+    "usage": [
+      "Backbone for finance agents' decision rules in blackroad-os-operator",
+      "Context for automated-finance architecture mappings"
+    ]
+  },
+  {
+    "id": "openstax-finance",
+    "title": "OpenStax Principles of Finance",
+    "author": "OpenStax",
+    "year": 2022,
+    "path": "TODO/pdfs/openstax-principles-of-finance.pdf",
+    "tags": ["finance", "education", "risk", "markets"],
+    "summary": "Open textbook covering fundamental finance concepts including time value of money, risk/return, and capital structure.",
+    "usage": [
+      "Baseline definitions for finance terminology in glossary",
+      "Supports regulatory-facing documentation for financial agents"
+    ]
+  },
+  {
+    "id": "industrial-automation-handbook",
+    "title": "Handbook of Industrial Automation",
+    "author": "Springer",
+    "year": 2013,
+    "path": "TODO/pdfs/industrial-automation-handbook.pdf",
+    "tags": ["automation", "systems", "control"],
+    "summary": "Reference for automation architectures, safety constraints, and control patterns applicable to orchestrated agents.",
+    "usage": [
+      "Inform automation patterns for finance orchestrator",
+      "Cross-reference for SIG factor mappings of capabilities"
+    ]
+  },
+  {
+    "id": "marketing-management-models",
+    "title": "Marketing Management Models",
+    "author": "Assorted",
+    "year": 2018,
+    "path": "TODO/pdfs/marketing-management-models.pdf",
+    "tags": ["marketing", "psychology", "models"],
+    "summary": "Survey of marketing and persuasion frameworks relevant to go-to-market agent behaviors and narrative shaping.",
+    "usage": [
+      "Feature library for agent capability scoring and SIG nodes",
+      "Source for contradiction scenarios between revenue and compliance goals"
+    ]
+  }
+]

papers/agent-architecture/contradiction-handling.md

@@ -0,0 +1,27 @@
+# Contradiction Handling in BlackRoad OS
+
+Agents operate in a trinary logic space (true, false, unknown) where contradictions are treated as signals rather than silent errors. BlackRoad OS treats conflicts as first-class events that demand routing, journaling, and potentially escalation to orchestrators or human operators.
+
+## What is a Contradiction?
+
+A contradiction occurs when two or more beliefs, observations, or recommended actions cannot simultaneously hold. Examples include conflicting risk assessments across agents or incompatible compliance flags in finance workflows.
+
+## Escalation Mechanism
+
+1. **Detection:** Agents flag contradictions when belief vectors clash or when policy checks diverge.
+2. **Event emission:** A contradiction event is emitted to the orchestrator or higher-level mediator.
+3. **Reconciliation:** The orchestrator aggregates evidence, applies policy (e.g., majority vote, priority weighting, or regulatory override), and proposes a resolution.
+4. **Outcome recording:** Both accepted and rejected branches are recorded for transparency and future replay.
+
+## Integration with PS-SHA∞
+
+Contradiction resolution steps are journaled as PS-SHA∞ entries:
+
+- Record the competing claims and confidence scores.
+- Capture the chosen resolution rule and rationale.
+- Link branches through `previousHash` values so discarded paths remain inspectable.
+
+## TODOs
+
+- Define standardized contradiction event payloads for ingestion by `blackroad-os-operator`.
+- Prototype escalation thresholds in `/experiments/contradiction-sim` to tune sensitivity.

papers/agent-architecture/trinary-logic.md

@@ -0,0 +1,26 @@
+# Trinary Logic in BlackRoad OS
+
+BlackRoad OS agents reason with three states: +1 (true/affirmed), 0 (unknown/undecided), and -1 (negated/contradictory). This representation keeps uncertainty explicit and allows contradictions to be managed rather than hidden.
+
+## Belief Representation
+
+- **Vectors of trinary values:** Each proposition maps to {+1, 0, -1} to capture stance and uncertainty.
+- **Confidence weights:** Optional weights can scale the impact of each value when aggregating across agents.
+- **Temporal context:** Beliefs can be journaled over time, enabling a PS-SHA∞-backed history of shifts.
+
+## Combination Rules
+
+- **AND:** Minimum of contributing values, keeping contradictions (-1) dominant over unknowns (0) and truths (+1).
+- **OR:** Maximum of contributing values, preferring truths (+1) but preserving contradictions when present.
+- **Consensus:** Weighted sums normalized to the trinary domain to find majority positions while surfacing disagreement.
+
+## Operational Patterns
+
+- **Decision gating:** Actions require +1 consensus or explicit override when -1 appears.
+- **Escalation triggers:** Presence of balanced +1 and -1 across critical propositions triggers contradiction events.
+- **Logging:** Every aggregation result is written as a PS-SHA∞ entry for auditability.
+
+## TODOs
+
+- Extend combination rules with temporal decay to emphasize recent evidence.
+- Define canonical proposition sets for finance, compliance, and platform operations.

papers/finance-automation/automated-finance-architecture.md

@@ -0,0 +1,26 @@
+# Automated Finance Architecture
+
+BlackRoad OS models finance automation through orchestrated agents that mirror traditional corporate finance controls while remaining auditable via PS-SHA∞ journaling. The architecture centers on eight core finance agents coordinated by a finance orchestrator and exposed through API and Prism views.
+
+## Core Components
+
+- **Finance orchestrator:** Routes tasks, enforces segregation of duties, and coordinates PS-SHA∞ logging.
+- **Core agents:** Close, treasury, FP&A, procurement, compliance, tax, reporting, and controls agents handle domain-specific actions.
+- **API + Prism views:** External interfaces for ingesting events, triggering workflows, and surfacing journaled outcomes.
+
+## Reference Foundations
+
+- **Corporate finance literature:** Valuation, risk, and capital structure concepts from Brealey and OpenStax guide agent policies and scenario modeling.
+- **Regulatory expectations:** FINRA/SEC focuses on suitability, surveillance, and market integrity influence orchestration rules.
+- **Automation handbooks:** Industrial automation patterns inform safety constraints, redundancy, and recovery strategies.
+
+## PS-SHA∞ Integration
+
+- Every financial action is journaled with hashes and prior links to preserve an auditable worldline.
+- Contradictions between agents (e.g., revenue vs. compliance) are recorded with resolution metadata.
+- Journal entries can be exported for external attestations or compliance tooling.
+
+## TODOs
+
+- Elaborate data contracts for each agent API and align with `schemas/journal-entry.schema.json`.
+- Prototype scenario simulations to stress-test segregation-of-duties policies.

papers/finance-automation/regulated-industry-considerations.md

@@ -0,0 +1,23 @@
+# Regulated Industry Considerations
+
+The finance automation vision is conceptual and aspirational; it is not a claim of compliance. The design aims to align with GAAP/IFRS expectations and regulatory frameworks such as FINRA and SEC while preserving flexibility for jurisdictional variation.
+
+## Accounting Alignment
+
+- **GAAP/IFRS hooks:** Journal entry structures can map to ledger postings and disclosures, supporting external reporting pipelines.
+- **Controls:** Segregation of duties and PS-SHA∞ journaling provide traceability for approvals and policy overrides.
+
+## Regulatory Overlays
+
+- **FINRA/SEC:** Suitability, best execution, market surveillance, and recordkeeping requirements inform orchestration rules and logging depth.
+- **AML/KYC:** Agents should integrate identity verification and suspicious activity patterns, with contradictions escalated when risk flags collide with revenue objectives.
+
+## Posture Statement
+
+- **Conceptual only:** These documents describe intended capabilities, not audited compliance states.
+- **Evidence-ready:** The combination of journaled actions and explicit contradiction handling is designed to support future attestations.
+
+## TODOs
+
+- Map specific regulatory controls to agent responsibilities and PS-SHA∞ fields.
+- Draft sample audit trails demonstrating how finance workflows surface and resolve conflicts.

papers/ps-sha-infinity/ps-sha-infinity.md

@@ -0,0 +1,38 @@
+# PS-SHA∞ Overview
+
+PS-SHA∞ defines a persistent, cryptographically anchored identity over time. It treats an agent's existence as a worldline of journaled states where every decision, observation, or action is hashed and chained, creating a tamper-evident record. The construct centers on resilient identity, lineage, and accountability rather than consensus or currency.
+
+## Motivations
+
+- **Agent identity persistence:** Agents must persist across sessions, deployments, and orchestrations with continuity of memory and accountability.
+- **Tamper-evident logs:** Decisions and context should be verifiable with cryptographic integrity, enabling post-hoc auditing and replay.
+- **Fine-grained audit trails in regulated contexts:** Financial and safety-critical domains require clear, inspectable history for control and regulatory overlays.
+
+## Core Properties
+
+- **Append-only:** Events are added in sequence without mutation, preserving historical fidelity.
+- **Hash-chained:** Each entry links to its predecessor via `previousHash` and a computed `hash`, producing a verifiable chain.
+- **Identity binding:** Entries bind to an `actorId` to maintain continuity of the agent or system worldline.
+- **Reconstructable worldline:** The sequence can be replayed to rebuild state, diagnose decisions, or generate attestations.
+
+## Relation to JournalEntry
+
+PS-SHA∞ entries mirror the `JournalEntry` shape outlined in `blackroad-os-core`:
+
+- `actorId`: identity of the agent or subsystem making the entry.
+- `actionType`: category of the action or observation.
+- `timestamp`: RFC 3339 timestamp capturing when the event was recorded.
+- `payload`: structured data describing the event.
+- `previousHash`: link to the prior entry, enabling chain verification.
+- `hash`: digest covering the entry content and `previousHash` to anchor integrity.
+
+## Intended Use
+
+- **Finance agents:** Treasury, close, and compliance flows journal every control-relevant action for audit and reconciliation.
+- **Contradiction resolution:** Conflicts and their resolutions are recorded, preserving both accepted and discarded branches for review.
+- **External attestation:** Future RoadChain or similar integrations can expose verifiable worldlines for regulators, partners, or auditors.
+
+## TODOs
+
+- Expand with specific hashing strategies and signature schemes once RoadChain primitives are finalized.
+- Formalize rotation and retention policies for long-lived agents and federated deployments.

papers/ps-sha-infinity/references.md

@@ -0,0 +1,6 @@
+# PS-SHA∞ References
+
+- Henk C. A. van Tilborg, *Fundamentals of Cryptology* — hash functions, MACs, and signature foundations for integrity and attestation.
+- Classic Merkle tree literature — append-only data structure patterns to support efficient verification and pruning.
+- Blockchain whitepapers (e.g., Bitcoin, Ethereum) — chaining and distributed integrity techniques informing RoadChain-inspired attestations.
+- NIST SP 800-57 and SP 800-63 — key management and digital identity guidance relevant to binding agents to cryptographic material.

papers/spiral-information-geometry/sig-factor-tree.md

@@ -0,0 +1,26 @@
+# SIG Factor Tree
+
+A SIG factor tree represents an agent or identity as a root node with branches that encode prime factors, attributes, and capabilities. The structure highlights how high-level intent decomposes into actionable, composable traits.
+
+## Structure
+
+- **Root (agent/identity):** The anchor of the tree, representing the worldline whose factors are being mapped.
+- **Branches (prime factors):** Core attributes such as mission, constraints, core capabilities, and ethical boundaries. Each branch can be tagged with weights or maturity levels.
+- **Leaves (concrete traits):** Specific skills, datasets, or controls that operationalize each factor. Leaves can point to datasets, models, or policy modules.
+
+## Mapping to SIG
+
+- **Angular placement:** Each branch aligns to an angle on the spiral, making categories visually separable.
+- **Radial layering:** Depth in the tree maps to radial distance; inner nodes are foundational, outer leaves are externally visible actions or artifacts.
+- **Composition:** Siblings can combine to form composite capabilities, enabling a readable map of how agents evolve.
+
+## Uses
+
+- **Agent identity graphs:** Provide a structured graph that links capabilities to an agent's PS-SHA∞ worldline.
+- **Capability composition:** Help orchestrators decide which capabilities to activate or quarantine when contradictions appear.
+- **Gap analysis:** Identify missing leaves or weak factors for targeted data collection or training.
+
+## TODOs
+
+- Define a serialization that aligns with `schemas/sig.schema.json` for automatic visualization.
+- Experiment with scoring factors to generate spiral coordinates for plotting.

papers/spiral-information-geometry/sig-overview.md

@@ -0,0 +1,28 @@
+# Spiral Information Geometry (SIG) Overview
+
+Spiral Information Geometry (SIG) frames knowledge, agents, and state transitions on a spiral manifold. Positions on the spiral capture both path dependency and growth, letting identities be located in a geometry that encodes recurrence, divergence, and convergence of information.
+
+## Intuition
+
+The spiral represents the "road" of an evolving system:
+
+- **Path dependency:** Movement along the spiral encodes history; nearby turns contain echoes of prior states.
+- **Growth:** Radial expansion reflects accumulation of capability, context, and commitments.
+- **Recurrence:** Angular positions revisit themes, allowing cyclic patterns to be recognized and journaled.
+
+## Components
+
+- **Factorization:** Prime factors or salient attributes define how an agent decomposes into building blocks. These factors map to angular slots or branches.
+- **Layers:** Radial layers capture maturity, certainty, or energy of a factor; inner layers represent seed states, while outer layers represent committed, externalized knowledge.
+- **Factor Trees:** Trees organize factors into nested structures that can be rendered onto the spiral to show composition and inheritance.
+
+## Applications
+
+- **Agent mapping:** Place agents or subsystems on the spiral to track capability clusters and blind spots.
+- **Contradiction surfacing:** Overlay contradictions as perturbations or opposing vectors at specific angles.
+- **Capability planning:** Use the spiral to plan expansion paths, balancing radial growth with angular diversity.
+
+## TODOs
+
+- Formalize a mapping from factor trees to spiral coordinates (radius, angle, rotation history).
+- Define metrics for distance and similarity between agents on the spiral.

schemas/agent-identity.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://blackroad.systems/schemas/agent-identity.json",
+  "title": "Agent Identity",
+  "type": "object",
+  "properties": {
+    "agentId": { "type": "string" },
+    "sigNodeId": { "type": "string", "description": "Reference to a SIG node describing this agent." },
+    "capabilities": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of capability identifiers bound to the agent."
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Optional annotations such as risk classification or jurisdiction. "}
+  },
+  "required": ["agentId", "createdAt"],
+  "additionalProperties": false
+}

schemas/journal-entry.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://blackroad.systems/schemas/journal-entry.json",
+  "title": "Journal Entry",
+  "description": "General journal entry schema aligned with PS-SHA∞ for agent and system logging.",
+  "type": "object",
+  "properties": {
+    "id": { "type": "string" },
+    "timestamp": { "type": "string", "format": "date-time" },
+    "actorId": { "type": "string" },
+    "actionType": { "type": "string" },
+    "payload": {},
+    "previousHash": { "type": "string" },
+    "hash": { "type": "string" },
+    "chainId": { "type": "string", "description": "Identifier for the journal chain or worldline." },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Optional structured metadata including contradiction flags or attestation references."
+    }
+  },
+  "required": ["id", "timestamp", "actorId", "actionType", "payload", "hash"],
+  "additionalProperties": false
+}

schemas/ps-sha-infinity.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://blackroad.systems/schemas/ps-sha-infinity.json",
+  "title": "PS-SHA∞ Journal Entry",
+  "type": "object",
+  "properties": {
+    "id": { "type": "string" },
+    "timestamp": { "type": "string", "format": "date-time" },
+    "actorId": { "type": "string" },
+    "actionType": { "type": "string" },
+    "payload": {},
+    "previousHash": { "type": "string" },
+    "hash": { "type": "string" },
+    "metadata": {
+      "type": "object",
+      "description": "Optional free-form metadata for chain analysis or attestations.",
+      "additionalProperties": true
+    }
+  },
+  "required": ["id", "timestamp", "actorId", "actionType", "payload", "hash"],
+  "additionalProperties": false
+}

schemas/sig.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://blackroad.systems/schemas/sig.json",
+  "title": "Spiral Information Geometry Node",
+  "type": "object",
+  "properties": {
+    "id": { "type": "string" },
+    "label": { "type": "string" },
+    "factors": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Prime factors or salient attributes attached to this node."
+    },
+    "weight": {
+      "type": "number",
+      "description": "Optional weight or maturity score for the node."
+    },
+    "children": {
+      "type": "array",
+      "items": { "$ref": "#" },
+      "description": "Nested SIG nodes representing factor decomposition."
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Arbitrary annotations such as spiral coordinates or risk flags."
+    }
+  },
+  "required": ["id", "label"],
+  "additionalProperties": false
+}