Layouts

Đầu vào là một yêu cầu nghiệp vụ viết bằng lời thường, và đầu ra là 3–4 phương án layout, mỗi phương án là một cấu trúc JSON để thầy chọn giữa chúng — hoặc một lời từ chối nêu tên quyết định sản phẩm còn thiếu. Đây không phải compiler: compiler trả về một đáp án vì luật của nó tự đóng lựa chọn. Ở đây lựa chọn là quyết định sản phẩm, nên trả về một đáp án là compiler đang giả vờ rằng người chủ đã quyết rồi.

Luật

Một phương án gọi tên các region, ai sở hữu hình học của từng region, cái gì mount một lần và cái gì đổi theo route. Nó không bao giờ gọi tên một class. Class được quyết sau, bằng luật, từ cái hình mà tầng này chấp nhận; một phương án mang class là đã tiêu một quyết định không thuộc quyền nó tiêu.

Mọi region đều trích một thứ có thật: một entry trong contract, hoặc một lời khai tường minh rằng cần một entry mới và vì sao. Region không trích gì cả là một thành phần bịa ra đang khoác cấu trúc JSON.

Đầu vào

Sáu, không hơn. Mỗi cái có mặt vì thiếu nó là hỏng một chuyện cụ thể.

Đầu vào số 2 cố ý loại mảng class. Contract 192KB rút còn 74KB — đúng 38% — khi chỉ lấy key, why, host và tên children. Cắt vậy không phải để tiết kiệm. Một tầng không thấy class thì không thể ghi class vào đầu ra của nó, nên “JSON không có class” được ép bằng thứ mình không đọc, chứ không bằng một lời nhắc phải tuân theo.

Không đọc ở tầng này: mảng class, biến theme, cài đặt của leaf và composite, dữ liệu và query, chữ theo locale, lint. Tất cả thuộc những tầng đến sau.

Đọc một yêu cầu

1. Liệt kê những bề mặt mà yêu cầu nói ra. Yêu cầu gọi tên một trang thì có một bề mặt; gọi tên một luồng thì có nhiều, và mỗi bề mặt một lô riêng.
2. Tra trước khi thiết kế. Với mỗi region, tra contract theo why — theo lý do, không theo hình. Hai entry cùng class mà khác lý do là hai entry khác nhau.
3. Chọn những trục mà các phương án sẽ khác nhau ở đó, lấy từ đầu vào số 5. Hai phương án trùng mọi giá trị trục là một phương án.
4. Gán người ghép cho từng region từ danh sách branch. Region có entry mà không có branch là chưa giải xong, không phải đã xong.
5. Đặt từng region vào bảng route: nó mount một lần rồi giữ, đổi theo route, hay mở ra như overlay?
6. Từ chối thay vì bịa. Quyết định mà yêu cầu không nói ra và cây không suy ra được thì trả về cho người chủ.

Trục khác biệt

Bộ đóng mà một phương án khác nhau ở đó. Mỗi giá trị là một sự thật cấu trúc, nói được trong một câu.

Phương án phải khai bộ giá trị trục của nó. Hai phương án trùng cả bộ là trùng lặp và một cái bị loại — máy thấy được chuyện đó, nên không người đọc nào phải tự thấy.

Phán quyết mỗi region

Mỗi region ra đúng một trong ba, và cái thứ ba là ngoại lệ:

generalize mà không có số call site đo được thì bị từ chối. Đổi tên là rẻ khi chỉ một file trích key, và là chuyện cả sản phẩm khi một branch dùng chung trích nó — mà contract không phân biệt được hai trường hợp đó.

Tên đã generic hoá vẫn phải cố định children. Nới flashcard-result-fact-row thành fact-row thì vẫn giữ một nhãn và một giá trị trên cùng baseline; nới tiếp thành row là gọi tên chẳng ràng buộc gì nữa.

Luật cho phương án

Mười hai luật mà mọi phương án phải thoả. Phương án phạm một luật không phải là phương án yếu hơn — nó không phải phương án, và đem nó vào 3–4 là tiêu sự chú ý của thầy vào thứ đã bị từ chối từ trước.

Quy tắc

1. Phương án không mang class, không mang token, không mang màu.
2. Mọi region trích một entry key, hoặc khai một entry mới kèm why của nó.
3. Mọi region gọi tên branch ghép nó.
4. Phương án khai bộ giá trị trục, và không hai phương án nào trong một lô trùng cả bộ.
5. 3–4 phương án khi yêu cầu cho phép hơn một cấu trúc; ít hơn khi nó không cho phép, kèm lý do. Không bao giờ nhồi cho đủ ba.
6. Quyết định sản phẩm còn thiếu thì trả về cho người chủ. Không bao giờ đoán để lô cho đủ.
7. JSON của phương án là dạng chuẩn hoá — thứ tự khoá cố định, không timestamp, không id theo lượt — vì hash của nó là thứ lời chấp thuận gắn vào.
8. Feedback mở một lượt mới. Phương án đã chấp nhận không bao giờ bị sửa tại chỗ.

Từ chối

Từ chối là một đầu ra, không phải một thất bại. Dùng nó khi:

• yêu cầu nói ra kết quả nhưng không nói ai sở hữu hình học của một region;
• hai region cùng đòi một field mà yêu cầu không nói bên nào sở hữu;
• một region cần một entry mà why của entry đó phản lại yêu cầu;
• một class cần dùng không có trong tập đóng của contract — khi đó nó là đổi contract, không phải một lựa chọn layout.

refusal: returned-to-owner
missing: <quyết định chưa ai đưa ra>
blocked: <những region không giải được nếu thiếu nó>

Đầu ra

Đầu ra chính là JSON, và thẩm quyền của nó là schema.json nằm cạnh bản ghi này — không phải cái trích đoạn dưới đây. envelope giữ những thứ đổi theo lượt; hash chỉ phủ một phương án, nên cùng một quyết định chạy lại ở lượt sau vẫn ra đúng hash đó.

{
  "schema": 1,
  "envelope": {
    "session": "course-catalogue/2026-08-18",
    "round": 1,
    "project": "starci-academy",
    "surface": "course-catalogue",
    "prompt": "yêu cầu, đúng nguyên văn",
    "contractAt": "trạng thái contract lúc giải"
  },
  "candidates": [
    {
      "id": "a",
      "axes": {"navigation": "navbar", "evidence": "beside", "secondary": "panel", "chrome": "sticky"},
      "citesPrecedent": "none",
      "regions": [
        {
          "name": "results",
          "entry": {"verdict": "reuse", "key": "course-catalogue-card"},
          "assembler": "SurfaceListCard",
          "mount": "per-route",
          "whyMatch": "a course is read as one offer with its own entry action"
        }
      ],
      "reason": "vì sao phương án này đáng để người chủ đọc"
    }
  ],
  "refusal": {"missing": "quyết định chưa ai đưa ra", "blocked": ["results"]}
}

Mọi object trong schema đều đặt additionalProperties: false, nên một className không phải là phát hiện để tranh luận — nó không hợp lệ. Validate trước khi ghi và trước khi hash:

node <trust>/scripts/validate-artifact.mjs --schema <trust>/brainstorms/layouts/schema.json --data <batch.json> --hash

Validator còn ép ba luật cấp-lô mà schema không nói được: không class token ở bất cứ đâu trong lô, không hai phương án trùng bộ trục, và phải có ít nhất một phương án trích none.

Ví dụ đã giải

Yêu cầu. “Catalogue khoá học: bộ lọc và kết quả, trên một trang.”

Yêu cầu nói ra một bề mặt và hai region. Nó không nói bộ lọc có được giữ khi đi vào một khoá rồi quay ra hay không, nên chuyện đó không được giả định.

{
  "schema": 1,
  "envelope": {
    "session": "course-catalogue/2026-08-18",
    "round": 1,
    "project": "starci-academy",
    "surface": "course-catalogue",
    "prompt": "A course catalogue: filters and the results, on one page.",
    "contractAt": "5eb4ac6a2463"
  },
  "candidates": [
    {
      "id": "a",
      "axes": {"navigation": "navbar", "evidence": "beside", "secondary": "panel", "chrome": "sticky"},
      "citesPrecedent": "none",
      "regions": [
        {
          "name": "filters",
          "entry": {"verdict": "new", "key": "catalogue-filter-rail", "why": "a filter set names what the result region is currently showing"},
          "assembler": "SurfacePanel",
          "mount": "per-route",
          "whyMatch": "a filter set names what the result region is currently showing"
        },
        {
          "name": "results",
          "entry": {"verdict": "reuse", "key": "course-catalogue-card"},
          "assembler": "SurfaceListCard",
          "mount": "per-route",
          "whyMatch": "a course is read as one offer with its own entry action"
        }
      ],
      "reason": "filters beside results keeps the current narrowing visible while reading, which is what a catalogue is scanned for"
    },
    {
      "id": "b",
      "axes": {"navigation": "rail", "evidence": "below", "secondary": "route", "chrome": "scrolls"},
      "citesPrecedent": "none",
      "regions": [
        {
          "name": "scopes",
          "entry": {"verdict": "generalize", "from": "flashcard-mode-tabs", "to": "mode-tabs", "callSites": 2},
          "assembler": "SurfaceCard",
          "mount": "mounts-once",
          "whyMatch": "a small closed set of scopes is switched between, not filtered by"
        }
      ],
      "reason": "if the real narrowing is a handful of scopes rather than many filters, a tab strip costs a fraction of the page a rail takes"
    }
  ],
  "refusal": {
    "missing": "whether a chosen filter set survives navigating into a course and back",
    "blocked": ["filters"]
  }
}

Đúng lô này validate được, và hai phương án của nó hash ra f5534ef5… với 75056f73…. Chạy lại nó ở lượt 7 với prompt viết lại hoàn toàn thì vẫn đúng hai hash đó, vì envelope nằm ngoài hash. Không có tính chất ấy thì lời chấp thuận đang gắn vào một con số tự nó đổi.

Lời từ chối giao kèm các phương án. Cả hai vẫn đọc được; chỉ giá trị mount là chưa giải, và nói ra điều đó có ích hơn là chọn một giá trị rồi sai một cách tự tin.

Phạm vi

Tầng này quyết định một bề mặt gồm những gì và ai ghép chúng. Nó không quyết định giải phẫu của một khối — đó là tầng sau — và không quyết định một class, đó là việc của luật. Mười hai luật mà một phương án phải thoả được phát biểu ở trên dưới dạng mã LAYOUT-n, nên phương án được đối chiếu với một mã trích dẫn được, không phải với trí nhớ của người đọc về cây legacy.