3.3 X：画质与笔触

{
  "version": 1,
  "tier": "X",
  "project": "stardust-inn",
  "note": "笔刷参数声明表（第 3 章 3.3，X 层）。这张表只声明「管线允许的笔刷参数范围」（尺寸/不透明度/流量/硬度），**不声明任何画质或笔触质量指标**——真实笔触质量需真实画师与真实环境，命令行不可复现（X）。可静态校验的只有结构、枚举、id 文法、参数范围与诚实性（不得把需真实环境的事声明成命令行可复现）。",
  "requiredFields": ["id", "brush", "sizePx", "opacityPercent", "flowPercent", "hardnessPercent", "reproducible"],
  "enums": {
    "brush": ["ink-pen", "round-soft", "flat-bristle", "chalk"],
    "reproducible": ["cli", "requires-real-env"]
  },
  "idPattern": "^brush_[a-z][a-z0-9-]*$",
  "range": {
    "sizePx": [1, 400],
    "opacityPercent": [1, 100],
    "flowPercent": [1, 100],
    "hardnessPercent": [0, 100]
  },
  "items": [
    { "id": "brush_ink-outline", "brush": "ink-pen", "sizePx": 4, "opacityPercent": 100, "flowPercent": 100, "hardnessPercent": 90, "reproducible": "cli" },
    { "id": "brush_fill-flat", "brush": "round-soft", "sizePx": 24, "opacityPercent": 100, "flowPercent": 80, "hardnessPercent": 100, "reproducible": "requires-real-env" },
    { "id": "brush_shade-soft", "brush": "round-soft", "sizePx": 40, "opacityPercent": 35, "flowPercent": 40, "hardnessPercent": 0, "reproducible": "requires-real-env" },
    { "id": "brush_texture-chalk", "brush": "chalk", "sizePx": 500, "opacityPercent": 60, "flowPercent": 55, "hardnessPercent": 20, "reproducible": "requires-real-env" },
    { "id": "brush_bristle-flat", "brush": "flat-bristle", "sizePx": 30, "opacityPercent": 70, "flowPercent": 65, "hardnessPercent": 70, "reproducible": "requires-real-env" }
  ]
}

#!/usr/bin/env python3
# file: sim/st03_brush_audit.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/st03_brush_audit.py
"""笔刷参数声明表的静态审计（第 3 章 3.3，S 层，服务于 X 层）。

3.3 整节标 X：**真实画质与笔触需真实画师与真实环境，命令行不可复现**。本脚本**不产出任何
画质或笔触指标**（那需要真实环境），只对「笔刷参数声明表」做三类**静态**检查：

* **结构**：必填字段、枚举取值、id 文法；
* **范围**：sizePx / opacityPercent / flowPercent / hardnessPercent 必须落在声明区间内；
* **诚实性**：`reproducible` 声明 `cli` 即为**过度承诺**——无真实画师与真实环境时，笔触与画质
  不可能由命令行复现。

落 out/st03_brush_audit.json 供 P 层对照。三类检查全不需要画笔，也就不会编造笔触数字。
"""
import hashlib
import json
import os
import re
import sys

ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
FAMILY = {"E_FIELD": "structure", "E_ENUM": "structure", "E_ID": "structure",
          "E_RANGE": "range", "E_OVERCLAIM": "honesty"}


def audit_item(item, cfg):
    errs = []
    for f in cfg["requiredFields"]:
        if f not in item:
            errs.append({"code": "E_FIELD", "token": f})
    for key, allowed in cfg["enums"].items():
        if key in item and item[key] not in allowed:
            errs.append({"code": "E_ENUM", "token": f"{key}={item[key]}"})
    if not re.match(cfg["idPattern"], str(item.get("id", ""))):
        errs.append({"code": "E_ID", "token": str(item.get("id", ""))})
    for key, (lo, hi) in cfg["range"].items():
        v = item.get(key)
        if isinstance(v, int) and not (lo <= v <= hi):
            errs.append({"code": "E_RANGE", "token": f"{key}={v}∉[{lo},{hi}]"})
    if item.get("reproducible") == "cli":
        errs.append({"code": "E_OVERCLAIM", "token": "cli"})
    return errs


def main() -> int:
    cfg = json.load(open(os.path.join(ROOT, "config/st03_brush.json"), encoding="utf-8"))
    violations = []
    for it in cfg["items"]:
        violations += [{"id": it.get("id"), **e} for e in audit_item(it, cfg)]
    violations.sort(key=lambda v: (v["id"], v["code"]))
    counts, fams = {}, {}
    for v in violations:
        counts[v["code"]] = counts.get(v["code"], 0) + 1
        fams[FAMILY[v["code"]]] = fams.get(FAMILY[v["code"]], 0) + 1
    n = len(cfg["items"])
    cli = sum(1 for it in cfg["items"] if it.get("reproducible") == "cli")
    keys = [f"{v['id']}:{v['code']}:{v['token']}" for v in violations]
    canon = json.dumps({"itemCount": n, "structure": fams.get("structure", 0),
                        "range": fams.get("range", 0), "honesty": fams.get("honesty", 0),
                        "cliCount": cli}, separators=(",", ":"), ensure_ascii=False)
    summary = {"project": cfg["project"], "tier": cfg["tier"], "itemCount": n,
               "structureViolations": fams.get("structure", 0), "rangeViolations": fams.get("range", 0),
               "honestyViolations": fams.get("honesty", 0), "violationCount": len(violations),
               "cliCount": cli, "cliPermille": cli * 1000 // n, "counts": counts,
               "violations": violations, "canonical": canon,
               "digest": hashlib.sha256(canon.encode("utf-8")).hexdigest()[:16],
               "violationDigest": hashlib.sha256("\n".join(keys).encode("utf-8")).hexdigest()[:16]}
    json.dump(summary, open(os.path.join(ROOT, "out/st03_brush_audit.json"), "w", encoding="utf-8"),
              ensure_ascii=False, indent=2, sort_keys=True)
    print(f"itemCount={n} structure={summary['structureViolations']} "
          f"range={summary['rangeViolations']} honesty={summary['honestyViolations']} "
          f"cliPermille={summary['cliPermille']}")
    for v in violations:
        print(f"  {v['id']:22s} {v['code']:12s} {v['token']}")
    print(f"digest={summary['digest']} violationDigest={summary['violationDigest']}")
    print("wrote out/st03_brush_audit.json")
    return 0


if __name__ == "__main__":
    sys.exit(main())

itemCount=5 structure=0 range=1 honesty=1 cliPermille=200
  brush_ink-outline      E_OVERCLAIM  cli
  brush_texture-chalk    E_RANGE      sizePx=500∉[1,400]
digest=8756f2b4121cf544 violationDigest=bf67e7c82283e7ed
wrote out/st03_brush_audit.json

// file: core/src/st03/brush.ts
// tier: P
// verify: node --test 'core/test/st03_*.test.ts'
// 笔刷参数声明表的 TS 侧静态审计（第 3 章 3.3）。与 sim/st03_brush_audit.py 共用
// config/st03_brush.json；判据全是字符串/整数（字段名、枚举、正则、整数区间），故两侧
// 违例集合逐位一致。**不产出任何画质或笔触指标**——那需要真实环境，命令行不可复现（X）。
// 只允许可擦除 TS 语法（禁 enum / namespace / 参数属性 / 装饰器）。

export type BrushItem = Record<string, unknown>;
export type BrushCfg = {
  requiredFields: string[]; enums: Record<string, string[]>; idPattern: string;
  range: Record<string, number[]>; items: BrushItem[];
};
export type Violation = { id: string; code: string; token: string };

const RANGE_KEYS = ["sizePx", "opacityPercent", "flowPercent", "hardnessPercent"];

export function auditItem(it: BrushItem, cfg: BrushCfg): Violation[] {
  const id = String(it.id ?? "");
  const out: Violation[] = [];
  const push = (code: string, token: string): void => void out.push({ id, code, token });
  for (const f of cfg.requiredFields) if (!(f in it)) push("E_FIELD", f);
  for (const [key, allowed] of Object.entries(cfg.enums)) {
    if (it[key] !== undefined && !allowed.includes(String(it[key]))) push("E_ENUM", `${key}=${it[key]}`);
  }
  if (!new RegExp(cfg.idPattern).test(id)) push("E_ID", id);
  for (const key of RANGE_KEYS) {
    const [lo, hi] = cfg.range[key];
    const v = it[key];
    if (typeof v === "number" && Number.isInteger(v) && !(lo <= v && v <= hi)) {
      push("E_RANGE", `${key}=${v}∉[${lo},${hi}]`);
    }
  }
  if (it.reproducible === "cli") push("E_OVERCLAIM", "cli");
  return out;
}

export function auditAll(cfg: BrushCfg): Violation[] {
  const all = cfg.items.flatMap((it) => auditItem(it, cfg));
  return all.sort((x, y) =>
    x.id < y.id ? -1 : x.id > y.id ? 1 : x.code < y.code ? -1 : x.code > y.code ? 1 : 0);
}

/** 诚实性千分比：把需真实环境的事声明成 cli 的比例，整数地板除。 */
export function cliPermille(cfg: BrushCfg): number {
  const cli = cfg.items.filter((it) => it.reproducible === "cli").length;
  return Math.floor((cli * 1000) / cfg.items.length);
}

/** canonical 摘要：键序固定，与 Python 侧同序、无空白，供 sha256 对拍。 */
export function canonical(cfg: BrushCfg): string {
  const vs = auditAll(cfg);
  const fam = (c: string): number => vs.filter((v) => v.code === c).length;
  const structure = vs.length - fam("E_RANGE") - fam("E_OVERCLAIM");
  return JSON.stringify({
    itemCount: cfg.items.length, structure, range: fam("E_RANGE"), honesty: fam("E_OVERCLAIM"),
    cliCount: cfg.items.filter((it) => it.reproducible === "cli").length,
  });
}

brush digest = 8756f2b4121cf544
✔ 跨语言：违例集合与两类摘要逐位一致（字符串/整数类） (1.718083ms)
✔ 诚实性：无真实环境时把笔触声明成命令行可复现即为过度承诺 (0.099ms)
✔ 负例：过度承诺、越界、id 不合文法、枚举非法，四类各自可被单独触发 (0.13375ms)
ℹ tests 3
ℹ pass 3
ℹ fail 0