VFS FEDERATION STUDIO v0.0.10 — P4 MONK LOOM NEURAL FOUNDATION HANDOFF
======================================================================

OUTCOME
-------
This cut introduces Monk Loom: a small deterministic neural attachment that is feasible in Pure
Perl, identity-bearing in Federation Image v2, and structurally unable to supersede Monk or commit
its own changes. It is a P4 foundation, not a claim that all P4 work is complete.

START HERE
----------
1. docs/architecture/MONK_LOOM_NEURAL_CONTRACT.md
2. docs/architecture/P4_NEURAL_FOUNDATION_STATUS.md
3. docs/architecture/P4_NEURAL_FOUNDATION_EVIDENCE.md
4. docs/architecture/OFFLINE_HELP_CONTRACT.md
5. src/vfs_federation_studio/domain/neural.py
6. src/vfs_federation_studio/federation/neural.py
7. perl_runtime_templates/compatibility/VFS/Federation/MonkLoom.pm

FROZEN DECISIONS
----------------
- Section type 12 is MONK_NEURAL_ATTACHMENT; required capability bit 3 is MONK_NEURAL.
- An attachment is invalid without section 11 and an exact canonical Monk fingerprint match.
- Adding/changing it changes image source identity through the NEURAL\0 manifest domain.
- v1 uses signed integer fixed point and truncation toward zero; no float is allowed.
- v1 activations are LINEAR and RELU; every layer saturates to the embedded value limit.
- Results are advisory evidence. They are never authorization or routing commands.
- Adaptation is optional, verified-feedback-bound, final-linear-head-only and proposal-only.
- Python and Pure Perl must produce identical evaluation, proposed attachment and proposal
  fingerprints for the same contract inputs.
- Ordinary writable image rebuilds preserve the attachment exactly.
- Offline help topic/context IDs are stable API for later desktop F1 integration.

PRIMARY API
-----------
Python:
  MonkNeuralAttachment / NeuralFeature / NeuralOutput / NeuralLayer
  MonkLoomEngine.evaluate(features)
  MonkLoomEngine.propose_adaptation(features, VerifiedNeuralFeedback)
  V2FederationRuntime.neural_evaluate(...)
  V2FederationRuntime.neural_propose_adaptation(...)

Perl:
  $runtime->monk_neural_attachment()
  $runtime->neural_evaluate(\%features)
  $runtime->neural_propose_adaptation(\%features, \%verified_feedback)

NEXT SAFE DEVELOPMENT SLICE
---------------------------
Build a presentation-only PySide model/evidence surface over these headless contracts, then wire F1
to the existing offline topic/context catalog. Keep model parsing, inference, adaptation and search
outside Qt. Require explicit user review before replacing an attachment in a candidate project.

Do not widen adaptation beyond the final head until there is a separate signed-evidence,
concurrency, rollback, resource-budget and governance design. Do not let a score become a Monk rule
or permission implicitly.

REMAINING CROSS-PROJECT WORK
----------------------------
- P3 regex wall-clock/preemption hardening.
- Bounded/mapped large diagnostic-image opening.
- Real PySide6 platform/accessibility/high-DPI qualification.
- Exact target-language confirmation before widening i18n catalogs.
- UI/project-store persistence for model configuration and evidence history.
- Optional cryptographic verifier/signature contract for feedback and accepted proposals.

VERIFICATION
------------
Use the commands in P4_NEURAL_FOUNDATION_EVIDENCE.md. Final observed results are recorded there
after clean regression and package proof: 146 Python tests passed, two optional PySide6 runtime
tests skipped, 86 Pure-Perl assertions passed, the standalone cross-runtime proof passed, and the
0.0.10 wheel built and passed a clean-install help/runtime resource smoke test.
