mylangiser 0.1.0

Generate progressive-disclosure interfaces from complex APIs via My-Lang
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

<!-- SPDX-License-Identifier: PMPL-1.0-or-later -->
<!-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> -->

# Mylangiser Topology

## Overview

Mylangiser is a progressive-disclosure interface generator. It analyses complex
API surfaces, assigns cognitive-load complexity scores, and generates layered
wrappers at three disclosure levels (@beginner, @intermediate, @expert).

## Module Map

```
mylangiser/
├── CLI Layer (Rust)
│   ├── src/main.rs              # Entry point: init, validate, generate, build, run, info
│   ├── src/lib.rs               # Library interface for programmatic use
│   ├── src/manifest/            # mylangiser.toml parser and validator
│   └── src/codegen/             # My-Lang layer generation pipeline
│
├── Verified Interface Seams
│   ├── src/interface/abi/       # Idris2 ABI (The Spec)
│   │   ├── Types.idr            # DisclosureLevel, ComplexityScore, APIEndpoint,
│   │   │                        # LayeredWrapper, SmartDefault, Result
│   │   ├── Layout.idr           # APISurfaceDescriptor, EndpointDescriptor,
│   │   │                        # WrapperDescriptor memory layouts
│   │   └── Foreign.idr          # FFI declarations: init, analyse_surface,
│   │                            # compute_scores, generate_layers, get_level
│   ├── src/interface/ffi/       # Zig FFI (The Bridge)
│   │   ├── build.zig            # Build config for libmylangiser (.so/.a)
│   │   ├── src/main.zig         # FFI implementation: Handle, scoring algorithm,
│   │   │                        # layer generation, smart default inference
│   │   └── test/                # Integration tests verifying ABI compliance
│   └── src/interface/generated/ # Auto-generated C headers (from Idris2 ABI)
│
├── Container Layer
│   ├── Containerfile            # OCI build (Chainguard base)
│   └── container/               # Stapeln container ecosystem
│
└── Governance Layer
    ├── .machine_readable/6a2/   # STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK
    ├── .machine_readable/anchors/ANCHOR.a2ml
    ├── .machine_readable/policies/
    ├── .machine_readable/contractiles/
    └── .machine_readable/bot_directives/
```

## Data Flow

```
                    mylangiser.toml
                         │
                         ▼
              ┌─────────────────────┐
              │  Manifest Parser    │  (Rust: src/manifest/)
              │  Parse endpoints,   │
              │  types, params      │
              └─────────┬───────────┘
                        │
                        ▼
              ┌─────────────────────┐
              │  API Surface        │  (Zig FFI: mylangiser_analyse_surface)
              │  Analysis           │
              │  Build endpoint     │
              │  model              │
              └─────────┬───────────┘
                        │
                        ▼
              ┌─────────────────────┐
              │  Complexity         │  (Zig FFI: mylangiser_compute_scores)
              │  Scoring            │
              │  Score 0-100 per    │
              │  endpoint           │
              └─────────┬───────────┘
                        │
                        ▼
              ┌─────────────────────┐
              │  Layer Generation   │  (Zig FFI: mylangiser_generate_layers)
              │  Assign disclosure  │
              │  levels, compute    │
              │  smart defaults     │
              └─────────┬───────────┘
                        │
                        ▼
              ┌─────────────────────┐
              │  Idris2 ABI Proofs  │  (Idris2: Types.idr, Layout.idr)
              │  Verify layer       │
              │  subset correctness │
              └─────────┬───────────┘
                        │
                        ▼
              ┌─────────────────────┐
              │  My-Lang Codegen    │  (Rust: src/codegen/)
              │  Emit @beginner,    │
              │  @intermediate,     │
              │  @expert wrappers   │
              └─────────┬───────────┘
                        │
                        ▼
                  Layered Wrapper
                  (drop-in library)
```

## Complexity Scoring Formula

```
score = (required_params * 3)
      + (optional_params * 1)
      + (type_depth * 5)
      + (error_surface * 2)

Clamped to [0, 100].
```

Thresholds (configurable in mylangiser.toml):
- 0-33: @beginner
- 34-66: @intermediate
- 67-100: @expert

## Layer Parameter Visibility

| Level          | Parameters visible         | Error messages      |
|----------------|----------------------------|---------------------|
| @beginner      | Required only              | Human-readable      |
| @intermediate  | Required + half optional   | Typed with context  |
| @expert        | All (required + optional)  | Raw codes + stack   |

## Key Invariants

1. **Layer ordering**: Beginner < Intermediate < Expert (never reversed)
2. **Parameter monotonicity**: beginner_params <= intermediate_params <= expert_params
3. **Score bounds**: 0 <= complexity_score <= 100
4. **Default safety**: smart defaults satisfy parameter type constraints
5. **Determinism**: same manifest always produces same output