3.1 导入设置与 .meta 语义

{
  "ruleSet": "meta",
  "specVersion": 1,
  "note": "导入侧车文件（.meta）的字段契约。判据：删掉该字段后无法从「源文件字节 + 命名规则 + 项目规范」重算出来的，才是契约字段（contract）；能重算的一律是派生字段（derived），写进 .meta 只会制造伪变更。",
  "policy": {"derivedDriftAllowed": 0, "note": "派生字段存储值与重算值不等即算漂移；契约字段缺失按角色分级"},
  "fields": [
    {"name": "guid", "class": "contract", "role": "identity", "required": true},
    {"name": "importer", "class": "contract", "role": "setting", "required": true},
    {"name": "maxSize", "class": "contract", "role": "setting", "required": true},
    {"name": "compression", "class": "contract", "role": "setting", "required": false},
    {"name": "wrapMode", "class": "contract", "role": "setting", "required": false},
    {"name": "sourceWidth", "class": "derived", "recomputeFrom": "width"},
    {"name": "sourceHeight", "class": "derived", "recomputeFrom": "height"},
    {"name": "fileBytes", "class": "derived", "recomputeFrom": "bytes"},
    {"name": "contentHash", "class": "derived", "recomputeFrom": "sha1"},
    {"name": "modifiedAt", "class": "derived", "recomputeFrom": "mtime"},
    {"name": "humanName", "class": "derived", "recomputeFrom": "basename"}
  ]
}

#!/usr/bin/env python3
# file: sim/ta03_meta.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/ta03_meta.py
"""3.1 的 S 层审计：把 .meta 的每个字段分到 contract / derived / unknown 三类，再判契约字段
有没有缺、派生字段的存储值与源文件真值是否漂移。落 out/ta03_meta.json 供 P 层跨语言对照。"""
import hashlib
import json
import os
import sys

ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
OUT = os.path.join(ROOT, "out")
CFG = os.path.join(ROOT, "config")


def audit(schema: dict, records: list) -> tuple:
    by_name = {f["name"]: f for f in schema["fields"]}
    counts = {"contract": 0, "derived": 0, "unknown": 0}
    issues = []
    for r in sorted(records, key=lambda x: x["id"]):
        meta, src = r["meta"], r["source"]
        for name in sorted(meta):
            f = by_name.get(name)
            if f is None:
                counts["unknown"] += 1
                issues.append({"id": r["id"], "code": "I_META_UNKNOWN_FIELD", "field": name})
            elif f["class"] == "contract":
                counts["contract"] += 1
            else:
                counts["derived"] += 1
                k = f.get("recomputeFrom")
                if k and k in src and str(meta[name]) != str(src[k]):
                    issues.append({"id": r["id"], "code": "W_META_DERIVED_DRIFT", "field": name,
                                   "stored": str(meta[name]), "actual": str(src[k])})
        for f in schema["fields"]:
            if f["class"] == "contract" and f["required"] and f["name"] not in meta:
                issues.append({"id": r["id"], "field": f["name"],
                               "code": "E_META_MISSING_IDENTITY" if f["role"] == "identity"
                                       else "E_META_MISSING_SETTING"})
    issues.sort(key=lambda v: (v["id"], v["code"], v["field"]))
    return counts, issues


def main() -> int:
    schema = json.load(open(f"{CFG}/ta03_meta_schema.json", encoding="utf-8"))
    records = json.load(open(f"{CFG}/ta03_import_records.json", encoding="utf-8"))["records"]
    counts, issues = audit(schema, records)
    keys = [f"{v['id']}:{v['code']}:{v['field']}"
            + (f":{v['stored']}->{v['actual']}" if "stored" in v else "") for v in issues]
    digest = hashlib.sha256("\n".join(keys).encode("utf-8")).hexdigest()[:16]
    report = {"project": "stardust-inn", "ruleSet": schema["ruleSet"], "recordCount": len(records),
              "fieldOccurrences": sum(counts.values()), "counts": counts, "digest": digest,
              "missingContract": sum(1 for v in issues if v["code"].startswith("E_META_MISSING")),
              "driftCount": sum(1 for v in issues if v["code"] == "W_META_DERIVED_DRIFT"),
              "unknownCount": sum(1 for v in issues if v["code"] == "I_META_UNKNOWN_FIELD"),
              "issueCount": len(issues), "issues": issues}
    os.makedirs(OUT, exist_ok=True)
    with open(f"{OUT}/ta03_meta.json", "w", encoding="utf-8") as f:
        json.dump(report, f, ensure_ascii=False, indent=2, sort_keys=True)
        f.write("\n")
    print(f"recordCount={len(records)} fieldOccurrences={report['fieldOccurrences']} "
          f"contract={counts['contract']} derived={counts['derived']} unknown={counts['unknown']}")
    print(f"missingContract={report['missingContract']} drift={report['driftCount']} "
          f"unknownField={report['unknownCount']} issues={len(issues)} digest={digest}")
    for v in issues:
        print(f"  {v['code']} {v['id']} {v['field']}"
              + (f" stored={v['stored']} actual={v['actual']}" if "stored" in v else ""))
    print("wrote out/ta03_meta.json")
    return 0


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

recordCount=9 fieldOccurrences=98 contract=43 derived=54 unknown=1
missingContract=2 drift=5 unknownField=1 issues=8 digest=693257bfa48a6230
  E_META_MISSING_SETTING char_innkeeper-idle_v01 maxSize
  W_META_DERIVED_DRIFT furn_chair-base_v01 sourceWidth stored=512 actual=300
  E_META_MISSING_IDENTITY vfx_steam-puff_v01 guid
wrote out/ta03_meta.json

// file: core/src/ta03/meta.ts
// tier: P
// verify: node --test 'core/test/ta03_*.test.ts'
// 3.1 的 P 层内核：与 sim/ta03_meta.py 共用同一份 config/ta03_meta_schema.json 与
// config/ta03_import_records.json。字段分类与漂移判据全是字符串比较，故两侧问题集合逐位一致。
// 只允许可擦除 TS 语法（禁 enum / namespace / 参数属性 / 装饰器）。

export type MetaField = { name: string; class: string; role?: string; required?: boolean; recomputeFrom?: string };
export type MetaSchema = { fields: MetaField[] };
export type MetaRecord = { id: string; meta: Record<string, unknown>; source: Record<string, unknown> };
export type MetaIssue = { id: string; code: string; field: string; stored?: string; actual?: string };
export type MetaCounts = { contract: number; derived: number; unknown: number };

const cmp = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);

export function auditMeta(schema: MetaSchema, records: MetaRecord[]): { counts: MetaCounts; issues: MetaIssue[] } {
  const byName = new Map<string, MetaField>();
  for (const f of schema.fields) byName.set(f.name, f);
  const counts: MetaCounts = { contract: 0, derived: 0, unknown: 0 };
  const issues: MetaIssue[] = [];
  for (const r of [...records].sort((a, b) => cmp(a.id, b.id))) {
    for (const name of Object.keys(r.meta).sort()) {
      const f = byName.get(name);
      if (f === undefined) {
        counts.unknown += 1;
        issues.push({ id: r.id, code: "I_META_UNKNOWN_FIELD", field: name });
      } else if (f.class === "contract") {
        counts.contract += 1;
      } else {
        counts.derived += 1;
        const key = f.recomputeFrom;
        if (key !== undefined && key in r.source && String(r.meta[name]) !== String(r.source[key])) {
          issues.push({ id: r.id, code: "W_META_DERIVED_DRIFT", field: name,
            stored: String(r.meta[name]), actual: String(r.source[key]) });
        }
      }
    }
    for (const f of schema.fields) {
      if (f.class === "contract" && f.required === true && !(f.name in r.meta)) {
        const code = f.role === "identity" ? "E_META_MISSING_IDENTITY" : "E_META_MISSING_SETTING";
        issues.push({ id: r.id, code, field: f.name });
      }
    }
  }
  issues.sort((x, y) => cmp(x.id, y.id) || cmp(x.code, y.code) || cmp(x.field, y.field));
  return { counts, issues };
}

/** 与 sim/ta03_meta.py 的 key 逐字一致，用于跨语言 digest。 */
export function issueKey(v: MetaIssue): string {
  const k = `${v.id}:${v.code}:${v.field}`;
  return v.stored === undefined ? k : `${k}:${v.stored}->${v.actual}`;
}

// file: core/test/ta03_meta.test.ts
// tier: P
// verify: node --test 'core/test/ta03_*.test.ts'
// 跨语言对照：读 sim/ta03_meta.py 落盘的 out/ta03_meta.json，断言 TS 侧 auditMeta 复算出的
// 字段分类与问题集合与之一致（字符串/整数类，逐位一致）。负例见后两条测试。
import test from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { auditMeta, issueKey } from "../src/ta03/meta.ts";

const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
const schema = JSON.parse(readFileSync(resolve(ROOT, "config/ta03_meta_schema.json"), "utf8"));
const records = JSON.parse(readFileSync(resolve(ROOT, "config/ta03_import_records.json"), "utf8")).records;
const py = JSON.parse(readFileSync(resolve(ROOT, "out/ta03_meta.json"), "utf8"));
const digest = (ls: string[]): string => createHash("sha256").update(ls.join("\n")).digest("hex").slice(0, 16);

test("跨语言：TS 字段分类与问题集合 == Python（逐位一致）", () => {
  const mine = auditMeta(schema, records);
  const theirs = (py.issues as { id: string; code: string; field: string }[]).map(issueKey);
  assert.deepEqual(mine.counts, py.counts);
  assert.deepEqual(mine.issues.map(issueKey), theirs);
  assert.equal(digest(mine.issues.map(issueKey)), py.digest);
  console.log(`meta digest = ${py.digest}`);
});

test("计数：98 = contract 43 + derived 54 + unknown 1；干净记录不报", () => {
  const { counts, issues } = auditMeta(schema, records);
  assert.deepEqual(counts, { contract: 43, derived: 54, unknown: 1 });
  assert.equal(counts.contract + counts.derived + counts.unknown, py.fieldOccurrences);
  assert.deepEqual(issues.filter((v) => v.id === "furn_lamp-base_v01"), []);
});

test("负例：派生字段漂移必须被检出（存储值 != 源文件真值）", () => {
  const drift = auditMeta(schema, records).issues.filter((v) => v.code === "W_META_DERIVED_DRIFT");
  assert.equal(drift.length, py.driftCount);
  assert.ok(drift.some((v) => v.id === "furn_chair-base_v01" && v.field === "sourceWidth"
    && v.stored === "512" && v.actual === "300"), "sourceWidth 漂移未报");
  assert.ok(drift.some((v) => v.id === "ui_panel-wood_v01" && v.field === "fileBytes"), "fileBytes 漂移未报");
});

test("负例：契约字段缺失按角色分级；未知字段报 info", () => {
  const { issues } = auditMeta(schema, records);
  assert.ok(issues.some((v) => v.id === "vfx_steam-puff_v01" && v.code === "E_META_MISSING_IDENTITY"));
  assert.ok(issues.some((v) => v.id === "char_innkeeper-idle_v01" && v.code === "E_META_MISSING_SETTING"));
  assert.deepEqual(issues.filter((v) => v.code === "I_META_UNKNOWN_FIELD").map((v) => v.field), ["pivotHint"]);
});

meta digest = 693257bfa48a6230
✔ 跨语言：TS 字段分类与问题集合 == Python（逐位一致）
✔ 计数：98 = contract 43 + derived 54 + unknown 1；干净记录不报
✔ 负例：派生字段漂移必须被检出（存储值 != 源文件真值）
✔ 负例：契约字段缺失按角色分级；未知字段报 info
ℹ pass 12
ℹ fail 0