// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
= NEUROSYM.a2ml Specification
:doctype: book
:toc: left
:toclevels: 3
:sectnums:
:source-highlighter: highlight.js
:icons: font

image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"]
image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"]
image:https://img.shields.io/badge/format-A2ML_Family-orange.svg[A2ML Family,link="https://github.com/hyperpolymath/standards"]

== Overview

NEUROSYM.a2ml defines **symbolic semantics** for operations. It specifies *meaning* -
composition rules, inversion semantics, and proof obligations - separate from
permission (META) or operational gating (AGENTIC).

NEUROSYM defines meaning. It does not grant permission.

Key capabilities:

* **Operation Semantics** - Forward and inverse definitions
* **Composition Rules** - How operations safely combine
* **Proof Obligations** - Verification interfaces for claims
* **Type System** - Semantic types for operations and data

== A2ML Format Family

This specification is part of the A2ML Format Family:

[cols="1,2,3"]
|===
|Format |Repository |Purpose

|META.a2ml
|link:../meta-a2ml/[meta-a2ml]
|Constitutional authority, architecture decisions

|STATE.a2ml
|Companion to META
|Project state tracking

|ECOSYSTEM.a2ml
|Companion to META
|Ecosystem positioning

|PLAYBOOK.a2ml
|link:../playbook-a2ml/[playbook-a2ml]
|Executable plans derived from META

|AGENTIC.a2ml
|link:../agentic-a2ml/[agentic-a2ml]
|Operational gating for AI agents

|**NEUROSYM.a2ml**
|neurosym-a2ml (this repo)
|**Symbolic semantics, proof obligations**

|ANCHOR.a2ml
|link:../anchor-a2ml/[anchor-a2ml]
|Project recalibration/realignment
|===

All formats are satellites of https://github.com/hyperpolymath/standards[hyperpolymath/standards].

== Execution Pipeline Position

NEUROSYM operates at step 3 in the execution pipeline:

[source]
----
1. META validation      <- Constitutional authority check
2. AGENTIC gating       <- Operational safety
3. NEUROSYM semantics   <- THIS SPECIFICATION
4. PLAYBOOK derivation  <- Build executable plan
5. Execution
6. ECOSYSTEM check
7. STATE update
----

== Key Concepts

=== Claim Types

Operations produce claims with different verification levels:

* **verified** - Operation outcome can be proven correct
* **unverified** - Outcome claimed but not proven
* **compensable** - Can be undone via compensating action
* **irreversible** - Cannot be undone

=== Proof Obligations

All claimed properties MUST have associated proof obligations:

[source,toml]
----
[neurosym.proof-obligations.content-integrity]
description = "Verify content has not been corrupted"
verification-method = "hash-comparison"
failure-action = "downgrade-to-unverified"
----

Failure to discharge a proof obligation MUST downgrade the claim. Claims are
NEVER silently preserved at a higher level than proven.

=== Composition Safety

When operations compose, claim types propagate conservatively:

* Sequential composition: weakest claim wins
* Parallel composition: weakest claim wins
* Conditional: branch-specific

== Quick Start

=== Minimal NEUROSYM.a2ml

[source,toml]
----
[neurosym]
project = "my-project"

[neurosym.operation-definitions.file-read]
forward-semantics = "Return file contents"
inverse = false
claim-type = "verified"
entropy-contribution = 1
----

See `examples/` for more complete examples.

== Specification

The complete normative specification is in link:spec/NEUROSYM-FORMAT-SPEC.adoc[spec/NEUROSYM-FORMAT-SPEC.adoc].

== Repository Structure

[source]
----
neurosym-a2ml/
+-- spec/
|   +-- NEUROSYM-FORMAT-SPEC.adoc   # Normative specification
+-- examples/
|   +-- minimal.a2ml                 # Minimal valid NEUROSYM file
|   +-- comprehensive.a2ml           # Full-featured example
+-- .machine_readable/
|   +-- STATE.a2ml                   # Project state
|   +-- META.a2ml                    # Architecture decisions
|   +-- ECOSYSTEM.a2ml               # Ecosystem position
+-- README.adoc                      # This file
----

== Contributing

Contributions are welcome. Please ensure:

* All changes follow the normative specification
* Examples validate against the spec
* SPDX license headers on all files

== License

PMPL-1.0-or-later. See LICENSE.
