@labpics/colors 0.9.1 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/LICENSES/CC-BY-4.0.txt +396 -0
- package/LICENSES/CC-BY-SA-4.0.txt +428 -0
- package/NOTICE.md +65 -0
- package/README.md +351 -282
- package/build-metadata.json +23 -0
- package/evidence/point-support-reference-surplus-q55-bps-proof-v1.json +1 -0
- package/evidence/wcag22-srgb8-q55-proof-v1.json +1 -0
- package/evidence/wcag22-srgb8-q55-v1.bin +0 -0
- package/evidence/wcag22-srgb8-v1.json +1 -0
- package/index.d.ts +211 -37
- package/index.js +499 -21
- package/package.json +40 -36
- package/pkg/labcolors.d.ts +230 -249
- package/pkg/labcolors.js +955 -157
- package/pkg/labcolors_bg.wasm +0 -0
- package/pkg/labcolors_bg.wasm.d.ts +61 -11
- package/pkg/snippets/labcolors-wasm-9fb8b927594c3d6f/inline0.js +98 -0
- package/program-wire/abi-v1.d.ts +84 -0
- package/program-wire/abi-v1.js +332 -0
- package/program-wire/abi-v2.d.ts +17 -0
- package/program-wire/abi-v2.js +61 -0
- package/program-wire/encoding.js +218 -0
- package/wcag22.d.ts +6 -0
- package/adapt-theme.d.ts +0 -74
- package/adapt-theme.js +0 -542
- package/apply-theme.d.ts +0 -16
- package/apply-theme.js +0 -44
- package/effective-bg.d.ts +0 -50
- package/effective-bg.js +0 -492
- package/watch-theme.d.ts +0 -57
- package/watch-theme.js +0 -144
package/README.md
CHANGED
|
@@ -1,282 +1,351 @@
|
|
|
1
|
-
# @labpics/colors
|
|
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
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
`
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
1
|
+
# @labpics/colors
|
|
2
|
+
|
|
3
|
+
Компилятор и runtime проверяемых цветовых Program-графов.
|
|
4
|
+
|
|
5
|
+
Клиент передаёт канонические Program wire-байты. Ядро атомарно проверяет граф, создаёт Session, принимает наблюдения среды и возвращает только сертифицированные Paint outputs. Recipe-меню ролей и специальные Material/Glow runtime-пути удалены из публичного API.
|
|
6
|
+
|
|
7
|
+
## Установка
|
|
8
|
+
|
|
9
|
+
Команда установки проверенного архива указана на [странице актуального релиза](https://github.com/Labpics-Team/lab-colors/releases/latest).
|
|
10
|
+
Она использует прямой URL конкретной версии, поэтому сохранённый lockfile
|
|
11
|
+
не зависит от будущих обновлений. Имя пакета и импорты остаются `@labpics/colors`.
|
|
12
|
+
|
|
13
|
+
[Готовый пример адаптации к фону](https://github.com/Labpics-Team/lab-colors/blob/main/docs/how-to/adapt-contrast.md) показывает выбор цвета и отказ при несовместимых требованиях.
|
|
14
|
+
|
|
15
|
+
## Первый маршрут
|
|
16
|
+
|
|
17
|
+
Инициализируйте WASM один раз выбранным способом, затем выполните общий пример
|
|
18
|
+
ниже в том же модуле.
|
|
19
|
+
|
|
20
|
+
### Браузер
|
|
21
|
+
|
|
22
|
+
В ESM-проекте с настройкой разрешения npm-импортов:
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import init from "@labpics/colors";
|
|
26
|
+
|
|
27
|
+
await init();
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Сборщик или сервер должен публиковать `pkg/labcolors_bg.wasm` рядом с
|
|
31
|
+
сгенерированным `pkg/labcolors.js`; `init()` загружает файл относительно этого
|
|
32
|
+
модуля. Если сборщик переносит WASM, передайте его URL явно через
|
|
33
|
+
`init({ module_or_path: wasmUrl })`.
|
|
34
|
+
|
|
35
|
+
### Node.js
|
|
36
|
+
|
|
37
|
+
В Node.js 22.11 или новее используйте ESM (`.mjs` или `"type": "module"` в
|
|
38
|
+
`package.json`) и передайте байты файла. Node.js не загружает `file:` URL через
|
|
39
|
+
`fetch`, поэтому браузерный вызов без аргументов здесь не подходит.
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { readFileSync } from "node:fs";
|
|
43
|
+
import init from "@labpics/colors";
|
|
44
|
+
|
|
45
|
+
await init({
|
|
46
|
+
module_or_path: readFileSync(
|
|
47
|
+
new URL(import.meta.resolve("@labpics/colors/pkg/labcolors_bg.wasm")),
|
|
48
|
+
),
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### Объявление графа и чтение результата
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
import { compileProgramWire } from "@labpics/colors";
|
|
56
|
+
import {
|
|
57
|
+
ProgramWireBuilderV1,
|
|
58
|
+
SURROUND_AVERAGE_V1,
|
|
59
|
+
WCAG22_SC1411_UI_COMPONENT_OR_STATE_V1,
|
|
60
|
+
} from "@labpics/colors/program-wire/abi-v1.js";
|
|
61
|
+
|
|
62
|
+
const programBytes = new ProgramWireBuilderV1()
|
|
63
|
+
.source(11, [20, 20, 20])
|
|
64
|
+
.fixedTarget(21, 11)
|
|
65
|
+
.surfaceInputPort(31)
|
|
66
|
+
.solidPaint(41, 21)
|
|
67
|
+
.inputSurface(51, 31)
|
|
68
|
+
.sourceOverOccurrence(61, 41, 51, 64, 0.2, SURROUND_AVERAGE_V1)
|
|
69
|
+
.presentationRoot(71, 61)
|
|
70
|
+
.presentationTarget(71, 61)
|
|
71
|
+
.wcag22VisibleUnary(true, 81, 61, WCAG22_SC1411_UI_COMPONENT_OR_STATE_V1)
|
|
72
|
+
.output(91, 41)
|
|
73
|
+
.finish();
|
|
74
|
+
const runtime = compileProgramWire(programBytes, 1);
|
|
75
|
+
try {
|
|
76
|
+
const snapshot = runtime.updateObserved(
|
|
77
|
+
1n,
|
|
78
|
+
new Uint32Array([1]),
|
|
79
|
+
new Uint8Array([255, 255, 255]),
|
|
80
|
+
1,
|
|
81
|
+
);
|
|
82
|
+
try {
|
|
83
|
+
if (snapshot.state === "ready") {
|
|
84
|
+
for (let index = 0; index < snapshot.outputCount(); index += 1) {
|
|
85
|
+
console.log(
|
|
86
|
+
snapshot.outputSlot(index),
|
|
87
|
+
snapshot.outputRgb(index),
|
|
88
|
+
snapshot.outputOpacity(index),
|
|
89
|
+
);
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
} finally {
|
|
93
|
+
snapshot.free();
|
|
94
|
+
}
|
|
95
|
+
} finally {
|
|
96
|
+
runtime.free();
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Канонические `LCPW` v1 bytes создаются `ProgramWireBuilderV1` или другим реализационно-независимым энкодером того же контракта.
|
|
101
|
+
|
|
102
|
+
## Явная конвенция cleanliness
|
|
103
|
+
|
|
104
|
+
Чтобы выбранный результат удовлетворял встроенной конвенции sRGB8, добавьте
|
|
105
|
+
`.declaredSrgb8CleanSet(true, 82, 71, 61)` в цепочку примера перед `.finish()`.
|
|
106
|
+
Здесь `82` — ID ограничения, `71` — presentation root, `61` — occurrence.
|
|
107
|
+
Проверяется финальный encoded-sRGB8 результат этой точки с учётом композиции,
|
|
108
|
+
а не только исходный цвет. `true` задаёт обязательное ограничение; `false`
|
|
109
|
+
не ограничивает выдачу outputs. Результаты отдельных report-only ограничений
|
|
110
|
+
публичный `ProgramSnapshot` не раскрывает.
|
|
111
|
+
|
|
112
|
+
Это явно выбранная, закреплённая версией пакета конвенция. Она не включается
|
|
113
|
+
автоматически и не подтверждает человеческое восприятие, фактическую отрисовку
|
|
114
|
+
или универсальную «чистоту» цвета.
|
|
115
|
+
|
|
116
|
+
Контракт использует закреплённый в пакете выпуск
|
|
117
|
+
`exact-nominal-srgb8-point-clean-set-v2`; его точная SHA-256 указана в `NOTICE.md`
|
|
118
|
+
пакета (в репозитории — `crates/labcolors-core/NOTICE.md`).
|
|
119
|
+
Это условная дискретная nominal-модель с воспроизводимым выводом, а не гарантия
|
|
120
|
+
человеческого восприятия. При обновлении пакета сохранённый wire следует заново
|
|
121
|
+
компилировать и оценивать: семантическая идентичность Program включает выпуск
|
|
122
|
+
конвенции, поэтому старые сертификаты не удостоверяют новый набор.
|
|
123
|
+
|
|
124
|
+
## Подключение к внешнему sink
|
|
125
|
+
|
|
126
|
+
Для сценария, где приложение само владеет DOM или другим renderer-surface,
|
|
127
|
+
используйте `attachProgramWire`. Синхронный `host` получает полный typed intent
|
|
128
|
+
(`setAll`, `revokeAll` или `confirmExact`) и должен вернуть `true` только после
|
|
129
|
+
атомарной установки всего принадлежащего ему scope; `false` отклоняет update.
|
|
130
|
+
Пакет не пишет DOM и не выдаёт authority из исходного или промежуточного Paint.
|
|
131
|
+
В примере `applyOwnedPointIntent` и `revokeOwnedPointScope` реализует приложение:
|
|
132
|
+
первая функция атомарно применяет intent и возвращает `boolean`, вторая
|
|
133
|
+
возвращает управление только после отзыва всего принадлежащего sink scope.
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
import { attachProgramWire } from "@labpics/colors";
|
|
137
|
+
|
|
138
|
+
const attachment = attachProgramWire(programBytes, 1, 91, 501, 71, 61, (intent) => {
|
|
139
|
+
// Приложение проверяет sinkOutput, expectedSequence и bindingEpoch,
|
|
140
|
+
// затем одним действием обновляет собственный renderer-surface.
|
|
141
|
+
return applyOwnedPointIntent(intent);
|
|
142
|
+
});
|
|
143
|
+
try {
|
|
144
|
+
const snapshot = attachment.updateObserved(
|
|
145
|
+
1n,
|
|
146
|
+
new Uint32Array([1]),
|
|
147
|
+
new Uint8Array([255, 255, 255]),
|
|
148
|
+
1,
|
|
149
|
+
);
|
|
150
|
+
try {
|
|
151
|
+
if (snapshot.state === "ready") {
|
|
152
|
+
const authority = attachment.materializationAuthority();
|
|
153
|
+
try {
|
|
154
|
+
console.log(authority.terminalCompositeRgb());
|
|
155
|
+
} finally {
|
|
156
|
+
authority.free();
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
} finally {
|
|
160
|
+
snapshot.free();
|
|
161
|
+
}
|
|
162
|
+
} finally {
|
|
163
|
+
revokeOwnedPointScope();
|
|
164
|
+
attachment.dispose(true);
|
|
165
|
+
attachment.free();
|
|
166
|
+
}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
`materializationAuthority()` читает только успешно установленный
|
|
170
|
+
attachment head. Его `rendererProvenance` остаётся `"unverified"`: результат —
|
|
171
|
+
модельная terminal materialization с проверенными identity, revision, sink stamp,
|
|
172
|
+
binding epoch и отсутствием downstream point, а не доказательство browser paint
|
|
173
|
+
или человеческого восприятия. При отказе host предыдущий head сохраняется.
|
|
174
|
+
Пока host callback исполняется синхронно, повторный вызов любой операции attachment,
|
|
175
|
+
включая `free()`, получает typed-отказ busy; освобождайте attachment после возврата
|
|
176
|
+
из callback. `free()` также получает typed-отказ `program_attachment_revoke_unconfirmed`,
|
|
177
|
+
пока внешний scope не отозван и `dispose(true)` не завершился успешно. Внешний scope
|
|
178
|
+
отзывается владельцем host до `dispose(true)`. Подтверждением служит только
|
|
179
|
+
примитивный `true`; числа, строки и объекты не приводятся к boolean и получают
|
|
180
|
+
`program_attachment_revoke_unconfirmed`.
|
|
181
|
+
|
|
182
|
+
`Symbol.dispose` и TypeScript `using` выполняют тот же защищённый `free()`.
|
|
183
|
+
До выхода из `using` приложение должно отозвать scope и вызвать `dispose(true)`;
|
|
184
|
+
автоматическое освобождение не подтверждает отзыв за внешнего владельца.
|
|
185
|
+
|
|
186
|
+
## Создание и инспекция certificate envelope
|
|
187
|
+
|
|
188
|
+
После инициализации WASM `issueSourceCertificateEnvelope()` возвращает новый
|
|
189
|
+
`Uint8Array` с envelope встроенного source producer Core. Функция не принимает
|
|
190
|
+
payload или identity. Например, после `await init()`:
|
|
191
|
+
|
|
192
|
+
```ts
|
|
193
|
+
import {
|
|
194
|
+
decodeCertificateEnvelope,
|
|
195
|
+
issueSourceCertificateEnvelope,
|
|
196
|
+
} from "@labpics/colors";
|
|
197
|
+
|
|
198
|
+
const bytes = issueSourceCertificateEnvelope();
|
|
199
|
+
const metadata = decodeCertificateEnvelope(bytes);
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Обе функции импортируются из `@labpics/colors`. `metadata.producerRevision` —
|
|
203
|
+
полный Git tree object ID исходников Core, а content identity адресует встроенный
|
|
204
|
+
source descriptor. Эти данные не утверждают равенство исполняемых файлов,
|
|
205
|
+
аутентичность удалённого отправителя или научные свойства цвета.
|
|
206
|
+
|
|
207
|
+
Если при сборке проверенный source descriptor недоступен, issuance бросает
|
|
208
|
+
ошибку с `operation: "issueSourceCertificateEnvelope"` и
|
|
209
|
+
`code: "certificate_producer_identity_unavailable"`. Её распознаёт
|
|
210
|
+
`isCertificateError`; untrusted decode и остальные операции остаются доступны.
|
|
211
|
+
|
|
212
|
+
`decodeCertificateEnvelope(bytes)` разбирает только фиксированный `LCEN` v1
|
|
213
|
+
transport envelope и возвращает замороженный metadata-object
|
|
214
|
+
`UntrustedCertificateEnvelopeV1`. Результат — метаданные framing и проверенные digest,
|
|
215
|
+
а не authority result и не доказательство
|
|
216
|
+
истины payload. Тело payload остаётся opaque и не передаётся в JavaScript.
|
|
217
|
+
|
|
218
|
+
До вызова WASM-функции фасад проверяет intrinsic storage `Uint8Array` и создаёт
|
|
219
|
+
собственный snapshot по правилам [допуска массивов](#массивы-на-границе-wasm).
|
|
220
|
+
Размер больше `MAX_CERTIFICATE_ENVELOPE_BYTES`
|
|
221
|
+
(`2097152`) отвергается до копирования, поскольку `wasm-bindgen` копирует typed array
|
|
222
|
+
в linear memory до входа Rust. Неизвестная schema, authority,
|
|
223
|
+
operation, payload type/version, неканоничные строки, trailing bytes и digest
|
|
224
|
+
mismatch дают typed error; `isCertificateError(value)` проверяет только
|
|
225
|
+
допустимую пару `operation`/`code`.
|
|
226
|
+
|
|
227
|
+
Заморожен внешний metadata-object; его три byte-поля — отдельные detached snapshots,
|
|
228
|
+
поэтому изменение буфера результата не меняет состояние WASM или следующий decode.
|
|
229
|
+
|
|
230
|
+
Создать envelope из произвольных JS-байтов, `ProgramSnapshot`, Paint, CSS, DOM или
|
|
231
|
+
materialization authority нельзя. Producer capability и admission ledger остаются
|
|
232
|
+
владением Rust Core; в r13 нет persistence, network relay, CLI, science authority
|
|
233
|
+
или registry publication.
|
|
234
|
+
|
|
235
|
+
## Контракт
|
|
236
|
+
|
|
237
|
+
- Один публичный runtime-root: `compileProgramWire` → `ProgramRuntime` → `ProgramSnapshot`.
|
|
238
|
+
- Обновление атомарно: отказ не публикует частичный state.
|
|
239
|
+
- Output появляется только при выполненных всех обязательных (`hard: true`) ограничениях. Это внутренняя проверка в рамках Session, а не публичный переносимый сертификат или гарантия конечного видимого результата приложения.
|
|
240
|
+
- Канонические байты имеют одну `ContentIdentity`.
|
|
241
|
+
- Невалидные wire-байты, графы, observation и resource bounds возвращают typed-отказы; fallback отсутствует.
|
|
242
|
+
- DOM и CSS не входят в ядро. Применение output принадлежит приложению.
|
|
243
|
+
|
|
244
|
+
## Числовые входы
|
|
245
|
+
|
|
246
|
+
ID потока и причины, число подложек и индекс output принимаются только как
|
|
247
|
+
конечные целые `number` в диапазоне `0..4294967295`. Ревизия принимается как
|
|
248
|
+
`bigint` в диапазоне `0n..18446744073709551615n`. Строки, нечисловые значения,
|
|
249
|
+
дроби и выход за диапазон не приводятся к допустимому значению. Допуск входа
|
|
250
|
+
предшествует изменению Session; после отказа корректную ревизию можно повторить.
|
|
251
|
+
Допустимость конкретного индекса, формы observations и порядка ревизий
|
|
252
|
+
по-прежнему проверяет соответствующий контракт runtime.
|
|
253
|
+
|
|
254
|
+
## Массивы на границе WASM
|
|
255
|
+
|
|
256
|
+
Program wire, поверхности и content identity принимают реальный `Uint8Array`,
|
|
257
|
+
ID сценариев — `Uint32Array`. Обычные массивы, другие виды typed array,
|
|
258
|
+
Proxy-обёртки, detached storage и собственные свойства `length`/`byteLength`
|
|
259
|
+
дают типизированный отказ до generated copier. Числа не оборачиваются и не
|
|
260
|
+
округляются неявно.
|
|
261
|
+
|
|
262
|
+
Допустимы `Buffer`, subclasses, subarray и массивы из другого realm, если их
|
|
263
|
+
внутренний тип соответствует аргументу. Фасад использует intrinsic storage,
|
|
264
|
+
не читает пользовательские getters и не обходит цепочку прототипов. Унаследованные
|
|
265
|
+
свойства размеров не участвуют в копировании; WASM получает отдельный snapshot.
|
|
266
|
+
Отказ observations сохраняет предыдущий head и допускает повтор той же ревизии.
|
|
267
|
+
Для `materializationAuthorityFor` identity должна содержать ровно 32 байта;
|
|
268
|
+
неверная длина отвергается до выделения snapshot.
|
|
269
|
+
|
|
270
|
+
## Распознавание ошибок
|
|
271
|
+
|
|
272
|
+
`isProgramError(value)` распознаёт ошибки Program по принадлежности текущему
|
|
273
|
+
`Error` и допустимой паре `operation`/`code`. Неизвестное значение, чужая пара
|
|
274
|
+
или исключение при чтении возвращают `false`, не заменяя исходную ошибку
|
|
275
|
+
новым исключением. Каждое поле читается не более одного раза, без преобразования
|
|
276
|
+
его значения; читаемые унаследованные поля и getters допустимы.
|
|
277
|
+
|
|
278
|
+
Нехватка ресурсов при compile/instantiate/update возвращает
|
|
279
|
+
`program_resource_exhausted`, внутренний сбой — `program_internal_invariant`.
|
|
280
|
+
Attachment сохраняет те же классы в `program_attachment_resource_exhausted`
|
|
281
|
+
и `program_attachment_internal_invariant`. Эти причины не означают, что
|
|
282
|
+
пользовательский граф или observation семантически недопустимы; отказ update
|
|
283
|
+
сохраняет предыдущий committed head и допускает повтор той же ревизии.
|
|
284
|
+
Нехватка памяти при подготовке identity для `materializationAuthorityFor`
|
|
285
|
+
также возвращает `program_attachment_resource_exhausted` с операцией
|
|
286
|
+
`materializationAuthority`.
|
|
287
|
+
|
|
288
|
+
Проверка описывает только наблюдённые значения. Она не удостоверяет происхождение
|
|
289
|
+
ошибки, не замораживает объект и не гарантирует неизменность следующих чтений
|
|
290
|
+
пользовательских getters. Непознанная ошибка остаётся у вызывающего приложения.
|
|
291
|
+
|
|
292
|
+
## Дополнительные функции
|
|
293
|
+
|
|
294
|
+
- `evaluateWcag22` — точная оценка WCAG 2.2 в finite sRGB8/Q55-профиле.
|
|
295
|
+
- `numericalCapabilityManifest` — манифест численных возможностей и доказательств сборки.
|
|
296
|
+
|
|
297
|
+
## Снимок входных массивов
|
|
298
|
+
|
|
299
|
+
Program wire, scenario IDs, surface bytes и certificate envelope принимают
|
|
300
|
+
типизированные массивы на обычном `ArrayBuffer`. Buffer, срезы и массивы из
|
|
301
|
+
другого JavaScript realm поддерживаются. Пакет делает собственную копию до
|
|
302
|
+
передачи в WASM и сохраняет прежнее состояние при отказе входа.
|
|
303
|
+
|
|
304
|
+
Массивы на `SharedArrayBuffer`, включая growable storage, получают штатный
|
|
305
|
+
typed-отказ входа: параллельный писатель может менять данные во время копирования.
|
|
306
|
+
Производитель наблюдения должен завершить запись и передать принадлежащий ему
|
|
307
|
+
обычный буфер. Это правило общее для компиляции, обновлений и идентичностей.
|
|
308
|
+
|
|
309
|
+
## Конечные варианты и явный порядок выбора
|
|
310
|
+
|
|
311
|
+
Для графа с `finiteTarget` используйте `ProgramWireBuilderV2` из
|
|
312
|
+
`@labpics/colors/program-wire/abi-v2.js`. Остальные методы описания графа
|
|
313
|
+
совпадают с V1. Готовые байты принимает прежний `compileProgramWire` или
|
|
314
|
+
`attachProgramWire`; второй решатель или отдельный lifecycle не нужны.
|
|
315
|
+
|
|
316
|
+
```js
|
|
317
|
+
builder.selectionRelease(1n, [
|
|
318
|
+
[{ id: 1, choices: [{ target: 21, candidate: 201 }] }],
|
|
319
|
+
[{ id: 2, choices: [{ target: 21, candidate: 202 }] }],
|
|
320
|
+
]);
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
Группы расположены от предпочтительной к следующей. Каждое состояние описывает
|
|
324
|
+
одновременно все конечные цели. Перечень должен покрывать полное произведение
|
|
325
|
+
доменов без повторов. Внутри одной группы порядок списка не влияет на решение:
|
|
326
|
+
ничья разрешается каноническими байтами непрозрачного ID состояния. Ревизия и
|
|
327
|
+
группы входят в идентичность выпуска выбора.
|
|
328
|
+
|
|
329
|
+
Core проверяет каждое состояние на всех наблюдаемых сценариях и выбирает первое,
|
|
330
|
+
которое прошло все обязательные ограничения. Неизвестный вход и конфликт
|
|
331
|
+
сохраняют существующие состояния Session и отзыв установленного результата.
|
|
332
|
+
Порядок задаёт предпочтения клиента; он не определяет cleanliness, не подбирает
|
|
333
|
+
научные коэффициенты и не ослабляет ограничения.
|
|
334
|
+
|
|
335
|
+
V2 допускает один выпуск выбора, до 4096 состояний и 4096 назначений суммарно.
|
|
336
|
+
V1 сохраняет прежние байты и отказывается от конечного графа без доступного ему
|
|
337
|
+
выпуска выбора. Нативные функции с суффиксом `_v1` остаются строго V1; функции
|
|
338
|
+
`check_program_wire` и `compile_program_wire` распознают обе поддерживаемые версии.
|
|
339
|
+
|
|
340
|
+
|
|
341
|
+
### Ошибки оценки и чтения результата
|
|
342
|
+
|
|
343
|
+
`isBindingError(error)` распознаёт `Error` по паре `operation` и `code`.
|
|
344
|
+
Для `evaluateWcag22` причины: `invalid_color`, `unknown_wcag22_criterion`,
|
|
345
|
+
`internal_error`. Для `numericalCapabilityManifest` доступен `internal_error`.
|
|
346
|
+
Неверный индекс в `outputSlot`, `outputRgb` или `outputOpacity` возвращает
|
|
347
|
+
`invalid_output_index` с операцией `readProgramOutput`; snapshot сохраняется.
|
|
348
|
+
|
|
349
|
+
Текст `message` служит диагностикой. Проверка читает каждое поле один раз,
|
|
350
|
+
не преобразует значения и возвращает `false` для неизвестной пары или ошибки
|
|
351
|
+
чтения. Контракт принадлежит также прямым WASM-входам.
|