RECOMMENDATIONS FOR IMPROVING COGNIA FROM THE XOR EXPERIMENT
============================================================

Date: July 31, 2026
Status: proposal for future implementation

1. UNIFY FORWARD AND GRADIENT SEMANTICS FOR GATED EDGES (HIGH PRIORITY)
------------------------------------------------------------------------

The forward contribution is:

    contribution = weight * pre_activation * clamp(gate_activation, 0, 1)

Every supervised weight update must use the same effective input:

    dWeight = error * derivative * pre_activation * gate_activation

Audit both `supervisedReadoutUpdate` (scalar delta/MSE) and
`supervisedSoftmaxReadoutUpdate` (softmax/cross-entropy). Add regression tests
proving that a closed gate produces exactly zero weight change and an open gate
matches an ungated edge. Add a four-conjunction, single-output XOR regression test.

2. DECLARE READOUTS AND TRAINABLE EDGES EXPLICITLY (HIGH PRIORITY)
-----------------------------------------------------------------

The trainer currently infers the readout from the top region and topology. This
becomes ambiguous with hidden layers, constructs, and multiple outputs. Suggested
syntax:

    output signal from output.result as xor {
        target: scalar;
        loss: mse;
        activation: raw;
        threshold: 0.5;
    }

or:

    training XorTraining {
        objective: supervised;
        features: feature.cells;
        target: output.result;
        loss: mse;
        learn: feature.cells -> output.result;
    }

`plasticity: learnable` should authorize supervised updates; `none` must always
remain fixed. The trainer should report selected trainable edge counts and ranges.
Selecting zero trainable edges should be an error rather than a silent run.

3. ADD NATIVE PRODUCT FEATURES (HIGH PRIORITY)
----------------------------------------------

XOR, contextual grammar, and control require conjunctions. Add a product that is
materialized as a named endpoint:

    feature xor01 = product(input.a0, input.b1);

or provide a standard `Product` construct. Its behavior must match across CPU and
CUDA forward paths, supervised gradients, persistence, and REST introspection.

4. ADD LIMITED DEEP CREDIT ASSIGNMENT (MEDIUM-HIGH PRIORITY)
-----------------------------------------------------------

Support training at least small feed-forward DAG subgraphs:

    sensory -> fixed/learnable features -> readout

This need not become a general autodiff framework initially. Store per-layer
activations, propagate deltas through tanh and gates, update only `learnable`
edges, preserve `fixed`/`state`/`derived` edges, and reject cycles in the trained
subgraph unless they are explicitly unrolled. Truncated BPTT or contrastive local
learning can follow for recurrent networks.

5. ADD A BINARY CLASSIFICATION OUTPUT (MEDIUM PRIORITY)
-------------------------------------------------------

`output signal` derives level from absolute activation, which is unsuitable when
a scalar value or sign carries class meaning. Add:

    output binary from output.result as xor {
        threshold: 0.5;
        labels: "0", "1";
    }

REST should return value, class, label, and threshold so clients do not need to
interpret raw `output[0]`.

6. MOVE INPUT PREPROCESSING INTO COGNIA (MEDIUM PRIORITY)
---------------------------------------------------------

PHP currently converts `(A,B)` into `[00,01,10,11]`. For reproducibility, feature
engineering should belong to the model. Add a declarative one-hot pair encoder or
allow pure expressions in an input adapter. REST could then accept raw `[A,B]`.

7. IMPROVE TRAINING DIAGNOSTICS (MEDIUM PRIORITY)
-------------------------------------------------

Add binary accuracy with a configurable threshold, a confusion matrix, weight
change statistics, selected readout edge counts, constant-output collapse
warnings, `--eval-only`, `--trace-sample N`, early stopping, and separate training
and validation datasets. These diagnostics would have exposed the gated output
collapse and increasing hidden-layer MSE immediately.

8. ADD NAMED DATASET SCHEMAS (LOW-MEDIUM PRIORITY)
--------------------------------------------------

The current `cognia-dataset 4 1` header carries dimensions but no semantics. A v2
format should declare input and target names, task type, and threshold. The trainer
could validate these against the model, and REST `/_model` could publish the same
schema.

9. ADD A TRAIN-SAVE-SERVE-EVALUATE INTEGRATION TEST (HIGH PRIORITY)
------------------------------------------------------------------

Create an automated test that parses the XOR model, trains with a fixed seed,
asserts 4/4 accuracy, saves the network, starts `cognia_serve` on loopback and a
free port, evaluates all four inputs, reloads and verifies identical decisions,
then stops the server and removes temporary artifacts. This covers the parser,
topology builder, CUDA runtime, trainer, persistence, and REST service.

10. RECOMMENDED IMPLEMENTATION ORDER
------------------------------------

    Step 1: fix and test `pre * gate` in scalar delta/MSE updates.
    Step 2: report and validate trainable readout edges.
    Step 3: add `output binary` and its REST representation.
    Step 4: add materialized `product` features as endpoints.
    Step 5: add an integration XOR test using raw `[A,B]` input.
    Step 6: add explicit training blocks and limited deep credit assignment.
    Step 7: add dataset schema v2 and declarative input transformations.

ACCEPTANCE TARGET
-----------------

After implementation, a Cognia model must accept two raw sensors `[A,B]`, create
its conjunctions internally, train without PHP feature engineering, survive
save/load, and classify all four XOR cases correctly through REST. PHP should only
send `[A,B]` and print the declared binary output.

