16.3 交付物与卷二衔接

{
  "project": "stardust-inn",
  "volume": "美术制作与视觉规范",
  "nextVolume": "技术美术与管线工程",
  "note": "卷一交付物清单。kind 三类：spec-text=给人读的规范文本，schema=机器校验的静态结构，runnable-artifact=可跑产物。handoffToVolume2 列出卷二接手的那批——只有 status=done 的交付物才允许被接手，且接手目标必须真实存在于清单里。",
  "requiredFields": ["id", "kind", "producer", "status"],
  "allowedKinds": ["spec-text", "schema", "runnable-artifact"],
  "allowedStatus": ["done", "in-progress", "planned"],
  "deliverables": [
    { "id": "spec.visual", "kind": "schema", "producer": "sim/consume.py", "status": "done" },
    { "id": "tokens.palette", "kind": "spec-text", "producer": "config/visual_spec.json", "status": "done" },
    { "id": "bible.template", "kind": "spec-text", "producer": "config/sp16_art_bible.json", "status": "done" },
    { "id": "manifest.schema", "kind": "schema", "producer": "config/sp06_manifest.schema.json", "status": "done" },
    { "id": "budget.geometry", "kind": "schema", "producer": "config/sp07_budget.json", "status": "done" },
    { "id": "budget.texture", "kind": "schema", "producer": "config/sp08_textures.json", "status": "done" },
    { "id": "atlas.spec", "kind": "schema", "producer": "config/sp10_atlas.json", "status": "done" },
    { "id": "lint.naming", "kind": "runnable-artifact", "producer": "core/src/sp05/naming.ts", "status": "done" },
    { "id": "check.dir-consistency", "kind": "runnable-artifact", "producer": "sim/sp06_dir.py", "status": "done" },
    { "id": "assembly.six-themes", "kind": "runnable-artifact", "producer": "sim/sp16_six.py", "status": "done" }
  ],
  "handoffToVolume2": [
    "spec.visual", "manifest.schema", "budget.geometry", "budget.texture",
    "atlas.spec", "lint.naming", "check.dir-consistency"
  ]
}

#!/usr/bin/env python3
# file: sim/sp16_handoff.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/sp16_handoff.py
"""16.3 交付物清单完整性 + 卷二接手的 S 层校验器。

读 config/sp16_deliverables.json，对卷一交付物清单做完整性校验，并校验交给卷二的
那批目标：字段齐全、kind/status 合法、id 唯一、handoff 目标存在且已 done。
违例字符串排序后落 out/sp16_handoff.json 供 P 层跨语言对照。
"""
import hashlib
import json
import os
import sys

ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))


def check(handoff: dict) -> list:
    req = handoff["requiredFields"]
    kinds, statuses = set(handoff["allowedKinds"]), set(handoff["allowedStatus"])
    items = handoff["deliverables"]
    ids = [d["id"] for d in items]
    known = set(ids)
    viol = []
    for d in items:
        for f in req:
            if not d.get(f):
                viol.append(f"MISSING_FIELD:{d.get('id', '?')}:{f}")
        if d.get("kind") not in kinds:
            viol.append(f"BAD_KIND:{d.get('id', '?')}:{d.get('kind')}")
        if d.get("status") not in statuses:
            viol.append(f"BAD_STATUS:{d.get('id', '?')}:{d.get('status')}")
        if ids.count(d.get("id")) > 1:
            viol.append(f"DUPLICATE_ID:{d.get('id')}")
    for target in handoff["handoffToVolume2"]:
        if target not in known:
            viol.append(f"DANGLING_HANDOFF:{target}")
            continue
        st = next(d["status"] for d in items if d["id"] == target)
        if st != "done":
            viol.append(f"HANDOFF_NOT_DONE:{target}:{st}")
    return sorted(set(viol))


def digest(handoff: dict, viol: list) -> str:
    parts = [f"{d['id']}:{d['kind']}:{d['status']}" for d in handoff["deliverables"]]
    parts += list(handoff["handoffToVolume2"]) + viol
    return hashlib.sha256(";".join(parts).encode("utf-8")).hexdigest()[:16]


def main() -> int:
    h = json.load(open(os.path.join(ROOT, "config/sp16_deliverables.json"), encoding="utf-8"))
    viol = check(h)
    by_kind = {}
    for d in h["deliverables"]:
        by_kind[d["kind"]] = by_kind.get(d["kind"], 0) + 1
    report = {"project": h["project"], "volume": h["volume"], "nextVolume": h["nextVolume"],
              "deliverableCount": len(h["deliverables"]), "byKind": by_kind,
              "handoffCount": len(h["handoffToVolume2"]), "handoff": h["handoffToVolume2"],
              "violations": viol, "count": len(viol)}
    report["digest"] = digest(h, viol)
    with open(os.path.join(ROOT, "out/sp16_handoff.json"), "w", encoding="utf-8") as f:
        json.dump(report, f, ensure_ascii=False, indent=2, sort_keys=True)
        f.write("\n")

    print(f"deliverables={report['deliverableCount']} handoff={report['handoffCount']} "
          f"violations={report['count']}")
    for k in sorted(by_kind):
        print(f"  {k:<18} {by_kind[k]}")
    for t in h["handoffToVolume2"]:
        print(f"  HANDOFF -> vol2 {t}")
    for v in viol:
        print(f"  VIOLATION {v}")
    print(f"digest={report['digest']}")
    print("wrote out/sp16_handoff.json")
    return 0


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

deliverables=10 handoff=7 violations=0
  runnable-artifact  3
  schema             5
  spec-text          2
  HANDOFF -> vol2 spec.visual
  HANDOFF -> vol2 manifest.schema
  HANDOFF -> vol2 budget.geometry
  HANDOFF -> vol2 budget.texture
  HANDOFF -> vol2 atlas.spec
  HANDOFF -> vol2 lint.naming
  HANDOFF -> vol2 check.dir-consistency
digest=c3440a00133c232d
wrote out/sp16_handoff.json

// file: core/src/sp16/handoff.ts
// tier: P
// verify: node --test 'core/test/sp16_*.test.ts'
// 16.3 交付物清单完整性的 P 层内核。与 sim/sp16_handoff.py 同一套规则：字段齐全、kind/
// status 合法、id 唯一、handoff 目标存在且已 done。只允许可擦除 TS 语法。

export function checkDeliverables(h: any): string[] {
  const req: string[] = h.requiredFields;
  const kinds = new Set<string>(h.allowedKinds);
  const statuses = new Set<string>(h.allowedStatus);
  const items = h.deliverables;
  const ids = items.map((d: any) => d.id);
  const known = new Set<string>(ids);
  const viol: string[] = [];

  for (const d of items) {
    for (const f of req) {
      if (!d[f]) viol.push(`MISSING_FIELD:${d.id ?? "?"}:${f}`);
    }
    if (!kinds.has(d.kind)) viol.push(`BAD_KIND:${d.id ?? "?"}:${d.kind}`);
    if (!statuses.has(d.status)) viol.push(`BAD_STATUS:${d.id ?? "?"}:${d.status}`);
    if (ids.filter((x: string) => x === d.id).length > 1) viol.push(`DUPLICATE_ID:${d.id}`);
  }
  for (const target of h.handoffToVolume2) {
    if (!known.has(target)) {
      viol.push(`DANGLING_HANDOFF:${target}`);
      continue;
    }
    const st = items.find((d: any) => d.id === target).status;
    if (st !== "done") viol.push(`HANDOFF_NOT_DONE:${target}:${st}`);
  }
  return [...new Set(viol)].sort();
}

// file: core/test/sp16_handoff.test.ts
// tier: P
// verify: node --test 'core/test/sp16_*.test.ts'
// 跨语言对照：读 sim/sp16_handoff.py 落盘的 out/sp16_handoff.json，断言 TS 侧的清单
// 完整性校验与 Python 逐位一致，并比对 sha256 指纹。负例：悬空接手目标、接手未完成
// 交付物、缺字段，都必须真的 fail。
import test from "node:test";
import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { checkDeliverables } from "../src/sp16/handoff.ts";

const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = resolve(HERE, "../..");
const h = JSON.parse(readFileSync(resolve(ROOT, "config/sp16_deliverables.json"), "utf8"));
const py = JSON.parse(readFileSync(resolve(ROOT, "out/sp16_handoff.json"), "utf8"));

const clone = (): any => JSON.parse(JSON.stringify(h));

test("交付物清单完整性：TS 与 Python 违例集合逐位一致", () => {
  assert.deepEqual(checkDeliverables(h), py.violations);
  assert.deepEqual(py.violations, []);
  assert.equal(py.deliverableCount, h.deliverables.length);
  assert.equal(py.handoffCount, h.handoffToVolume2.length);
});

test("sha256 指纹跨语言一致", () => {
  const parts = h.deliverables.map((d: any) => `${d.id}:${d.kind}:${d.status}`);
  const all = [...parts, ...h.handoffToVolume2, ...checkDeliverables(h)];
  const digest = createHash("sha256").update(all.join(";"), "utf8").digest("hex").slice(0, 16);
  assert.equal(digest, py.digest);
});

test("负例：接手一个不存在的交付物 → DANGLING_HANDOFF", () => {
  const b = clone();
  b.handoffToVolume2.push("spec.ghost");
  assert.ok(checkDeliverables(b).includes("DANGLING_HANDOFF:spec.ghost"));
});

test("负例：接手一个还没 done 的交付物 → HANDOFF_NOT_DONE", () => {
  const b = clone();
  b.deliverables.find((d: any) => d.id === "atlas.spec").status = "in-progress";
  assert.ok(checkDeliverables(b).includes("HANDOFF_NOT_DONE:atlas.spec:in-progress"));
});

test("负例：缺字段与非法 kind 都必须 fail", () => {
  const b = clone();
  delete b.deliverables[0].producer;
  b.deliverables[1].kind = "video";
  const v = checkDeliverables(b);
  assert.ok(v.includes("MISSING_FIELD:spec.visual:producer"), v.join(","));
  assert.ok(v.includes("BAD_KIND:tokens.palette:video"), v.join(","));
});

✔ 交付物清单完整性：TS 与 Python 违例集合逐位一致 (0.997334ms)
✔ sha256 指纹跨语言一致 (0.423209ms)
✔ 负例：接手一个不存在的交付物 → DANGLING_HANDOFF (0.163625ms)
✔ 负例：接手一个还没 done 的交付物 → HANDOFF_NOT_DONE (0.104583ms)
✔ 负例：缺字段与非法 kind 都必须 fail (0.10125ms)
ℹ tests 14
ℹ pass 14
ℹ fail 0