@starci/skills 1.1.0

package/operators/frontend-presentation-resolve/self-test.mjs

@@ -0,0 +1,163 @@
+// Proves validate.mjs on a synthetic session branch: one conforming resolution of a three-node tree
+// (one application-owned gap, one Grammar-owned padding, one recorded gap), one branch with the
+// contract emission off, one blocked on RULE_MISSING before anything was written, and one mutation
+// per law, each of which must fail with a line that names the defect.
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { validateResolutionStep } from './validate.mjs';
+
+const TREE = 'response/artifacts/plan-picker.resolved.tsx';
+const MAIN = 'body>main';
+const SECTION = 'body>main>section';
+const ASIDE = 'body>aside';
+const FINGERPRINT = `sha256:${'a'.repeat(64)}`;
+
+const inventory = () => ({
+  treeFingerprint: FINGERPRINT,
+  classNames: ['gap-6', 'gap-1'],
+  ruleIds: ['GAP-5', 'GAP-1'],
+  gaps: [{ nodePath: ASIDE, property: 'gap', missingPath: 'Common exposes no public path for the compact identity pair' }],
+});
+
+const resolvedTree = ({ emission = 'on' } = {}) => (emission === 'on'
+  ? `export default function PlanPicker() {
+  return (
+    <main className="gap-6" data-contract="GAP-5">
+      <SurfaceCard />
+      <aside className="gap-1" data-contract="GAP-1" />
+    </main>
+  );
+}
+`
+  : `export default function PlanPicker() {
+  return (
+    <main className="gap-6">
+      <SurfaceCard />
+      <aside className="gap-1" />
+    </main>
+  );
+}
+`);
+
+const responseMd = ({ gaps = 1, removed = 1 } = {}) => `# frontend-presentation-resolution — plan-picker
+
+## Owner map
+
+| Node | Property | Owner | Rule |
+| --- | --- | --- | --- |
+| \`${MAIN}\` | gap | app | \`GAP-5\` |
+| \`${SECTION}\` | padding | grammar | \`PADDING-4\` |
+| \`${ASIDE}\` | gap | app | \`GAP-1\` |
+
+## Rules chosen
+
+| Node | Rule | Class | Condition |
+| --- | --- | --- | --- |
+| \`${MAIN}\` | \`GAP-5\` | \`gap-6\` | region stack inside the page shell |
+| \`${ASIDE}\` | \`GAP-1\` | \`gap-1\` | the compact identity pair |
+
+## Removed
+
+| Node | Class | Because |
+| --- | --- | --- |
+${removed ? `| \`${SECTION}\` | \`p-4\` | reimplements an owned relationship |` : ''}
+
+## Gaps
+
+| Node | Property | Missing path |
+| --- | --- | --- |
+${gaps ? `| \`${ASIDE}\` | gap | Common exposes no public path for the compact identity pair |` : ''}
+
+## Fallbacks taken
+
+| Code | Action |
+| --- | --- |
+`;
+
+const requestJson = ({ extra = {} } = {}) => ({
+  schemaVersion: 9,
+  operatorId: 'frontend.presentation.resolve',
+  step: 2,
+  parallel: 1,
+  sessionId: 's-test',
+  contexts: [{ alias: '@knowledge/ui/presentation', head: null }, { alias: '@grammar/core', head: null }, { alias: '@workspaces/fe', head: 'd'.repeat(40) }],
+  requirements: { maxRounds: 2, contractEmission: 'on', resume: null, ...extra },
+  inputs: { 'frontend-direction-decision': 'step-1/parallel-1/response/response.md' },
+  resume: null,
+});
+
+const responseJson = ({ status = 'done', stop, fields, fallbacks = [], next = ['frontend.source.apply'] } = {}) => ({
+  schemaVersion: 9,
+  operatorId: 'frontend.presentation.resolve',
+  step: 2,
+  parallel: 1,
+  status,
+  ...(stop ? { stop } : {}),
+  fallbacks,
+  fields: fields ?? { 'frontend-presentation-resolution': 'response/response.md', inventory: 'response/data/inventory.json', 'resolved-tree': TREE },
+  commits: [],
+  next,
+});
+
+function writeBranch(files) {
+  const session = mkdtempSync(path.join(tmpdir(), 'fe-resolve-session-'));
+  const branch = path.join(session, 'step-2', 'parallel-1');
+  for (const d of ['request', 'response/data', 'response/artifacts']) mkdirSync(path.join(branch, d), { recursive: true });
+  mkdirSync(path.join(session, 'step-1', 'parallel-1', 'response'), { recursive: true });
+  writeFileSync(path.join(session, 'step-1', 'parallel-1', 'response', 'response.md'), '# frontend-direction-decision — plan-picker\n');
+  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', chain: [['1/1'], ['2/1']], steps: { '1/1': 'frontend.direction.decide', '2/1': 'frontend.presentation.resolve' }, current: '2/1', status: 'running' }));
+  for (const [name, content] of Object.entries(files)) {
+    if (content === null) continue;
+    writeFileSync(path.join(branch, name), typeof content === 'string' ? content : JSON.stringify(content, null, 2));
+  }
+  return { branch, session };
+}
+
+const baseline = () => ({
+  'request/request.json': requestJson(),
+  'response/response.json': responseJson(),
+  'response/response.md': responseMd(),
+  'response/data/inventory.json': inventory(),
+  [TREE]: resolvedTree(),
+});
+
+async function expectValid(files, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateResolutionStep(branch);
+  rmSync(session, { recursive: true, force: true });
+  assert.deepEqual(errors, [], `${label} should be valid`);
+}
+async function expectError(files, needle, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateResolutionStep(branch);
+  rmSync(session, { recursive: true, force: true });
+  assert.ok(errors.some((e) => e.includes(needle)), `${label}: expected an error containing "${needle}", got:\n${errors.join('\n') || '(none)'}`);
+}
+const mutate = (change) => { const m = inventory(); change(m); return { ...baseline(), 'response/data/inventory.json': m }; };
+
+await expectValid(baseline(), 'one application-owned gap, one Grammar-owned padding, one recorded gap');
+await expectValid({ ...baseline(), 'request/request.json': requestJson({ extra: { contractEmission: 'off' } }), [TREE]: resolvedTree({ emission: 'off' }) }, 'contract emission off leaves the tree bare');
+await expectValid({ 'request/request.json': requestJson(), 'response/response.json': responseJson({ status: 'blocked', stop: 'RULE_MISSING', next: [], fields: {} }) }, 'blocked on RULE_MISSING before anything was written');
+
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { mystery: 1 } }) }, 'requirements.mystery is not a field', 'undeclared requirement');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { maxRounds: 0 } }) }, 'maxRounds must be a positive whole number', 'no rounds allowed');
+await expectError(mutate((m) => { m.ruleIds.push('GAP-99'); }), 'is outside the published presentation inventory', 'unpublished rule');
+await expectError(mutate((m) => { m.classNames.push('gap-11'); }), 'is in the inventory and not in the resolved tree', 'class that never reached the tree');
+await expectError(mutate((m) => { m.treeFingerprint = 'nope'; }), 'treeFingerprint', 'inventory schema');
+await expectError({ ...baseline(), [TREE]: resolvedTree().replace(' data-contract="GAP-1"', '') }, 'no node claims it under data-contract', 'applied rule with no claim');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { contractEmission: 'off' } }) }, 'contract emission is off and the resolved tree carries a data-contract', 'claims written under emission off');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('| `body>main` | `GAP-5` | `gap-6` |', '| `body>main` | `GAP-5` | `gap-5` |'), 'response/data/inventory.json': (() => { const m = inventory(); m.classNames = ['gap-5', 'gap-1']; return m; })(), [TREE]: resolvedTree().replace('gap-6', 'gap-5') }, 'renders GAP-5 as gap-5, expected step 6', 'ordinal written as the step');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace(`| \`${SECTION}\` | padding | grammar | \`PADDING-4\` |`, `| \`${SECTION}\` | padding | app | \`PADDING-4\` |`) }, 'owns PADDING-4 and chooses no class for it', 'application claims an owned property and writes nothing');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace(`| \`${ASIDE}\` | \`GAP-1\` | \`gap-1\` | the compact identity pair |`, `| \`${SECTION}\` | \`PADDING-4\` | \`p-4\` | the card inset |`) }, 'chooses a class for PADDING-4, which Grammar already owns', 'application reimplements a Grammar relationship');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace(`| \`${MAIN}\` | gap | app | \`GAP-5\` |`, `| \`${MAIN}\` | gap | app | \`GAP-5\` |\n| \`${MAIN}\` | gap | app | \`GAP-4\` |`) }, 'decides gap more than once in the owner map', 'one property decided twice');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ gaps: 0 }) }, 'the Gaps table and inventory.gaps differ', 'gap recorded in data and not for the reader');
+await expectError(mutate((m) => { m.gaps = []; }), 'the Gaps table and inventory.gaps differ', 'gap recorded for the reader and not in data');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('| `p-4` | reimplements an owned relationship |', '| `gap-6` | reimplements an owned relationship |') }, 'and the inventory still carries it', 'class removed and still inventoried');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('## Removed', '## Deleted') }, 'missing section ^## Removed$', 'receipt section renamed');
+await expectError({ ...baseline(), 'response/data/inventory.json': null, 'response/response.json': responseJson({ fields: { 'frontend-presentation-resolution': 'response/response.md', 'resolved-tree': TREE } }) }, 'required output inventory is not in fields', 'missing required output');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ status: 'blocked', stop: 'MADE_UP_CODE', next: [] }) }, 'not a registered code', 'unknown stop code');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ fallbacks: ['RULE_MISSING'] }) }, 'has disposition terminate under these requirements', 'a terminate code taken as a fallback');
+
+process.stdout.write('frontend.presentation.resolve self-test: 3 valid branches, 18 rejected mutations\n');

package/operators/frontend-presentation-resolve/validate.mjs

@@ -0,0 +1,143 @@
+// frontend.presentation.resolve's own law over one branch, on top of the shared step check: every rule the
+// inventory carries is one @knowledge/ui/presentation actually publishes; every class the inventory
+// carries appears in the resolved tree; a Grammar-owned property emits no application class while an
+// application-owned one emits a class whose step matches the ordinal of its rule; the gaps the
+// receipt lists are exactly the gaps the inventory records; and with emission on every claimed rule
+// reaches the tree as a data-contract token.
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { validateStep } from '../../scripts/validate-step.mjs';
+import { tableUnder } from '../../scripts/validate-response.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const empty = (v) => v === undefined || v === null || v === '' || v === '—';
+const list = (v) => (Array.isArray(v) ? v : empty(v) ? [] : [v]);
+
+// The scale topics publish an ordinal rule identifier while the utility scale publishes a step
+// number, and the two diverge above the fourth value. Writing the ordinal as the class is the defect
+// this map exists to catch: GAP-5 renders `gap-6`, never `gap-5`.
+const ORDINAL_TO_STEP = { 0: '0', 1: '1', 2: '2', 3: '3', 4: '4', 5: '6', 6: '8' };
+const SCALE_PATTERN = {
+  GAP: /^gap(?:-[xy])?-([0-9]+)$/,
+  PADDING: /^p(?:[xytrbse])?-([0-9]+)$/,
+  MARGIN: /^-?m(?:[xytrbse])?-([0-9]+)$/,
+};
+const prefixOf = (ruleId) => ruleId.slice(0, ruleId.lastIndexOf('-'));
+const ordinalOf = (ruleId) => Number(ruleId.slice(ruleId.lastIndexOf('-') + 1));
+
+// The bound inventory is what @knowledge/ui/presentation publishes: one `## PREFIX-n` heading per rule.
+export async function publishedRuleIds(root = ROOT) {
+  const dir = path.join(root, 'knowledge', 'ui', 'presentation');
+  const ids = new Set();
+  if (!existsSync(dir)) return ids;
+  for (const name of (await readdir(dir)).filter((f) => f.endsWith('.md') && !f.endsWith('.vi.md') && f !== 'INDEX.md')) {
+    const text = await readFile(path.join(dir, name), 'utf8');
+    for (const m of text.matchAll(/^##\s+([A-Z][A-Z0-9-]*-[0-9]+)\b/gm)) ids.add(m[1]);
+  }
+  return ids;
+}
+
+export async function validateResolutionStep(branchDir, root = ROOT) {
+  const base = await validateStep(root, branchDir);
+  const errors = [...base.errors];
+  const { response, requirements = {}, present = new Set() } = base;
+  if (!response || response.operatorId !== 'frontend.presentation.resolve') return { errors };
+  const has = (f) => existsSync(path.join(branchDir, f));
+  const read = (f) => readFile(path.join(branchDir, f), 'utf8');
+
+  const maxRounds = Number(requirements.maxRounds ?? 2);
+  if (!Number.isInteger(maxRounds) || maxRounds < 1) errors.push(`request.json: maxRounds must be a positive whole number, not ${requirements.maxRounds}`);
+  const emission = requirements.contractEmission ?? 'on';
+
+  let inventory = null;
+  if (present.has('inventory') && has('response/data/inventory.json')) {
+    try { inventory = JSON.parse(await read('response/data/inventory.json')); } catch { inventory = null; }
+  }
+  if (!inventory) {
+    if (response.status === 'done') errors.push('response/data/inventory.json: a done branch needs the inventory');
+    return { errors };
+  }
+  const at = 'response/data/inventory.json';
+
+  const published = await publishedRuleIds(root);
+  for (const ruleId of inventory.ruleIds) {
+    if (!published.has(ruleId)) errors.push(`${at}: rule ${ruleId} is outside the published presentation inventory (UNKNOWN_RULE)`);
+  }
+
+  // The resolved tree is the only place the classes may land, so every class the inventory claims
+  // must actually be in it.
+  const treeRefs = list(response.fields?.['resolved-tree']);
+  let tree = null;
+  for (const ref of treeRefs) if (has(ref)) tree = await read(ref);
+  if (tree === null) { if (response.status === 'done') errors.push('response/artifacts: the resolved tree is missing'); }
+  else {
+    for (const className of inventory.classNames) {
+      if (!tree.includes(className)) errors.push(`${at}: class ${className} is in the inventory and not in the resolved tree`);
+    }
+    if (emission === 'on') {
+      for (const ruleId of inventory.ruleIds) {
+        const claimed = [...tree.matchAll(/data-contract="([^"]*)"/g)].some((m) => m[1].split(/\s+/).includes(ruleId));
+        if (!claimed) errors.push(`${at}: rule ${ruleId} is applied and no node claims it under data-contract`);
+      }
+    } else if (/data-contract=/.test(tree)) errors.push('response/artifacts: contract emission is off and the resolved tree carries a data-contract attribute');
+  }
+
+  if (present.has('frontend-presentation-resolution') && has('response/response.md')) {
+    const text = await read('response/response.md');
+    const rel = 'response/response.md';
+    const owners = tableUnder(text, '## Owner map') ?? [];
+    const chosen = tableUnder(text, '## Rules chosen') ?? [];
+    const removed = tableUnder(text, '## Removed') ?? [];
+    const gaps = tableUnder(text, '## Gaps') ?? [];
+
+    const appRules = new Set();
+    const grammarRules = new Set();
+    const seen = new Set();
+    for (const [node, property, owner, rule] of owners) {
+      const key = `${node}|${property}`;
+      if (seen.has(key)) errors.push(`${rel}: ${node} decides ${property} more than once in the owner map`);
+      seen.add(key);
+      (owner === 'app' ? appRules : grammarRules).add(`${node}|${rule}`);
+    }
+    for (const [node, rule, className] of chosen) {
+      if (grammarRules.has(`${node}|${rule}`)) { errors.push(`${rel}: ${node} chooses a class for ${rule}, which Grammar already owns`); continue; }
+      if (!appRules.has(`${node}|${rule}`)) { errors.push(`${rel}: ${node} chooses ${rule} without an application-owned row in the owner map`); continue; }
+      if (!inventory.ruleIds.includes(rule)) errors.push(`${rel}: ${node} chooses ${rule}, which the inventory does not carry`);
+      if (!inventory.classNames.includes(className)) errors.push(`${rel}: ${node} writes ${className}, which the inventory does not carry`);
+      const pattern = SCALE_PATTERN[prefixOf(rule)];
+      if (pattern) {
+        const expected = ORDINAL_TO_STEP[ordinalOf(rule)];
+        const steps = className.split(/\s+/).map((token) => pattern.exec(token)).filter(Boolean).map((m) => m[1]);
+        if (expected !== undefined) {
+          if (steps.length === 0) errors.push(`${rel}: ${node} emits no class for ${rule}`);
+          else if (!steps.includes(expected)) errors.push(`${rel}: ${node} renders ${rule} as ${className}, expected step ${expected}`);
+        }
+      }
+    }
+    for (const key of appRules) {
+      const [node, rule] = key.split('|');
+      if (!chosen.some(([n, r]) => n === node && r === rule)) errors.push(`${rel}: ${node} owns ${rule} and chooses no class for it`);
+    }
+    for (const [node, className] of removed) {
+      if (inventory.classNames.includes(className)) errors.push(`${rel}: ${node} removed ${className} and the inventory still carries it`);
+    }
+
+    // The gaps a reader sees and the gaps the machine carries are one list.
+    const receiptGaps = gaps.map(([node, property, missing]) => `${node}|${property}|${missing}`).sort();
+    const dataGaps = inventory.gaps.map((g) => `${g.nodePath}|${g.property}|${g.missingPath}`).sort();
+    if (receiptGaps.join('\n') !== dataGaps.join('\n')) {
+      errors.push(`${rel}: the Gaps table and inventory.gaps differ (${receiptGaps.length} rows against ${dataGaps.length})`);
+    }
+  }
+  return { errors };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const target = process.argv[2];
+  if (!target) { process.stderr.write('usage: node validate.mjs <session>/step-N/parallel-M\n'); process.exit(2); }
+  const { errors } = await validateResolutionStep(path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('valid frontend.presentation.resolve branch\n');
+}

package/operators/frontend-source-apply/errors.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": 9,
+  "note": "Stop codes frontend.source.apply emits. Same entry shape as operators/errors.json, scope implicit. Shared codes (INVALID_INPUT, SOURCE_DRIFT, NO_PROGRESS) come from operators/errors.json. OWNER_CONFLICT is also emitted here but is defined in operators/frontend-presentation-resolve/errors.json; it belongs in operators/errors.json with every emitting operator in scope.",
+  "codes": {
+    "RESOLUTION_STALE": {
+      "domain": "resolution",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The resolution actually read differs from the resolution the request bound.",
+        "vi": "Resolution thực sự đọc được khác resolution mà request đã bind."
+      },
+      "resume": {
+        "en": "Bind the current resolution, or resolve the tree again.",
+        "vi": "Bind resolution hiện tại, hoặc resolve lại cây."
+      }
+    },
+    "WRITE_REJECTED": {
+      "domain": "caller",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A file or a value the write would produce lies outside what was authorized, or the committed tree is not the resolved tree.",
+        "vi": "Một file hay một giá trị lần ghi sẽ tạo ra nằm ngoài phần đã được uỷ quyền, hoặc cây đã commit không phải cây đã resolve."
+      },
+      "resume": {
+        "en": "Declare a corrected write set, or publish a resolution that carries the value.",
+        "vi": "Khai lại write set cho đúng, hoặc publish một resolution có mang giá trị đó."
+      }
+    }
+  }
+}

package/operators/frontend-source-apply/operator.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 9,
+  "id": "frontend.source.apply",
+  "domain": "frontend",
+  "job": "Write one already-resolved tree into product source inside a frozen owner ceiling and a declared file set, emitting only values the bound resolution receipt already contains.",
+  "package": "operator.md",
+  "errors": "errors.json",
+  "validator": "validate.mjs",
+  "selfTest": "self-test.mjs",
+  "resources": {
+    "profile": "luna",
+    "grammarBound": true,
+    "tools": {
+      "@tools/fileread": "context-aliases",
+      "@tools/sourcewrite": "declared-write-set",
+      "@tools/git": "commit-session-branch",
+      "@tools/imagegen": "judged"
+    }
+  }
+}

package/operators/frontend-source-apply/operator.md

@@ -0,0 +1,127 @@
+# frontend.source.apply
+
+## Job
+
+Write one already-resolved tree into product source on the session branch, inside a frozen owner
+ceiling and a declared file set, emitting only values the bound resolution already contains, and
+account for every byte that entered the repository in one commit.
+
+## The single writer
+
+This is the only operator in the frontend pipeline that writes product source. Direction decides what
+to build and writes nothing; resolution decides every value and writes only its own artifact; the
+audit observes and writes nothing. One writer exists so that one receipt can account for every byte
+that entered the repository, which is impossible when three operators each write a little. Because it
+is the only writer, it is also the only place a fabricated value could enter source, and it has no way
+to produce one.
+
+## The session branch
+
+The operator never writes on the person's checked-out branch. It writes only on `session/<sessionId>`
+of the routed checkout, in the git worktree the orchestrator prepared from the frozen head, and it
+holds an exclusive lease on that worktree while it writes. The declared write set is committed exactly
+once; `response.json` carries that one sha under `commits`, the `changes.md` Binding row reads
+`@workspaces/fe` at the base head then the new sha on `session/<sessionId>`, and the next requests pin
+`@workspaces/fe` at that sha. Nothing is pushed and nothing is merged here: `git.publish` owns both.
+
+## No invented value
+
+Every class the write produces already appears in the bound resolution's class inventory, and every
+identifier it carries into a claim already appears in the applied rule inventory. Both lists are
+complete and frozen. A class absent from the resolution is `WRITE_REJECTED`: there is no rounding to a
+nearby value, no copying from a neighbouring file, and no reformatting that changes a step. A file the
+write would touch that the write set does not declare is `WRITE_REJECTED` too, even when it plainly
+needs the change; the correct next step is a corrected write set, not a wider write. A declared path
+whose owner root does not contain it is `OWNER_CONFLICT`, because owner membership alone is not the
+ceiling. The inventory check runs on the projection, before anything is written, so a rejected
+application leaves source untouched.
+
+## An application-owned node becomes an empty leaf
+
+When the direction marks a node as owned by the application, a canvas for instance, the projection
+writes an empty leaf file that carries that node's contract, its props and its states, so the tree
+compiles and the surface can be rendered and measured. The operator never writes that leaf's logic:
+the contract is what the direction decided, and the behaviour behind it belongs to whoever owns the
+node.
+
+## Unchanged is a measurement
+
+Every declared path is hashed before the projection and after the commit. A path whose projection
+differs from its current content is created or modified; a path whose projection equals it is recorded
+`unchanged`. After the commit the tree is read back and compared against the resolved tree, and a
+difference is `WRITE_REJECTED` rather than a silent success. Under `mode = dry` nothing is written at
+all: the branch emits the plan in `response/data/writes.json` with a null commit and stops there.
+
+## Boundary
+
+The operator writes the declared write-set paths on the session branch of `@workspaces/fe`, each under
+a mutable owner root, and its own `response/`. It does not write a class, value or rule identifier
+absent from the bound resolution, decide a presentation value, choose a Grammar component, restructure
+the tree, write the logic of an application-owned leaf, touch a file outside the declared write set,
+commit to any other branch, push, merge, edit knowledge, publish Grammar, change the resolution, start
+or reconfigure runtime services, or record a verdict, score or pass claim on the applied source. It
+knows what it wrote, never how it renders.
+
+## Context
+
+| Alias | Bind | Required |
+| --- | --- | --- |
+| `@workspaces/fe` | the routed frontend checkout at the frozen head; the write lands on its session branch and nowhere else | yes |
+
+## Inputs
+
+| Kind | From | Required |
+| --- | --- | --- |
+| `frontend-presentation-resolution` | `frontend.presentation.resolve`, the resolved tree and, beside it, the frozen class and rule inventory | yes |
+| `frontend-direction-decision` | `frontend.direction.decide`, the intent and the owner ceiling; never a source of values | yes |
+
+## Requirements
+
+| Field | Type | Default | Ask |
+| --- | --- | --- | --- |
+| `mode` | choice | apply | `apply` writes and commits, `dry` emits the plan and writes nothing |
+| `resume` | token | null | The blocked branch's token when re-entering after a stop |
+
+## Steps
+
+| # | Step | Params | Reads | Writes | Stops with |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Validate the gate and resume, and confirm the head | `resume`, `mode` | `request/request.json`, input `frontend-presentation-resolution`, @workspaces/fe at the frozen head | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Bind the resolution, the direction and the declared write set | — | inputs `frontend-presentation-resolution` (tree fingerprint, class and rule inventory, resolved tree) and `frontend-direction-decision` (intent and owner ceiling), @workspaces/fe (the declared paths and their owner roots) | — | `RESOLUTION_STALE`, `OWNER_CONFLICT` |
+| 3 | Project the resolved tree onto the declared paths | — | input `frontend-presentation-resolution` (the resolved tree), @workspaces/fe (the declared write set) | — | — |
+| 4 | Check every produced value against the inventory | `mode` | input `frontend-presentation-resolution` (the inventory beside the receipt) | `response/data/writes.json` | `WRITE_REJECTED` |
+| 5 | Write atomically on the session branch and commit once | — | @workspaces/fe (the current content of each declared path, under an exclusive lease) | @workspaces/fe/branch/session, `response/data/writes.json`, @tools/sourcewrite, @tools/git, image assets the direction judged, @tools/imagegen | — |
+| 6 | Read the tree back at the commit | — | @workspaces/fe at the commit | — | `WRITE_REJECTED` |
+| 7 | Emit | — | everything above | `response/response.md`, `response/changes.md`, `response/response.json` | — |
+
+Under `mode = dry` the branch stops after step 4 with the plan alone: `writes.json` carries a null
+commit, `response.json` carries no commit, and the checkout is untouched. Under `apply`, step 5 writes
+and commits exactly once and step 6 proves that the committed tree is the resolved tree. `changes.md`
+is the record the next steps read: which paths moved, which claims they carry, which gates the
+checkout pins for them, and which surfaces must now be observed.
+
+## Outputs
+
+| Kind | File | Type | Required |
+| --- | --- | --- | --- |
+| `frontend-source-application` | `response/response.md` | md | yes |
+| `changes` | `response/changes.md` | md | yes |
+| `writes` | `response/data/writes.json` | data | yes |
+
+## Stops
+
+| Code | Disposition |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `OWNER_CONFLICT` | terminate |
+| `RESOLUTION_STALE` | terminate |
+| `WRITE_REJECTED` | terminate |
+| `NO_PROGRESS` | terminate |
+
+## Next
+
+| When | Operator |
+| --- | --- |
+| the source is committed and the rendered surface must be measured | `frontend.surface.audit` |
+| the source is committed and the checkout's own gates must run | `quality.verify` |

package/operators/frontend-source-apply/operator.vi.md

@@ -0,0 +1,126 @@
+# frontend.source.apply
+
+## Việc
+
+Ghi một cây đã resolve vào source sản phẩm trên nhánh phiên, bên trong một trần owner đã đóng băng và
+một tập file đã khai, chỉ phát ra những giá trị mà resolution được bind đã chứa sẵn, và chịu trách
+nhiệm cho từng byte đã vào repository trong đúng một commit.
+
+## Người ghi duy nhất
+
+Đây là operator duy nhất trong chuỗi frontend ghi source sản phẩm. Direction quyết dựng cái gì và
+không ghi gì; resolution quyết mọi giá trị và chỉ ghi artifact của chính nó; audit quan sát và không
+ghi gì. Một người ghi duy nhất tồn tại để một biên nhận duy nhất chịu trách nhiệm cho từng byte đã vào
+repository, điều bất khả thi khi ba operator mỗi anh ghi một ít. Vì là người ghi duy nhất, nó cũng là
+chỗ duy nhất một giá trị bịa có thể lọt vào source, nên nó không có đường nào để tạo ra một giá trị
+như vậy.
+
+## Nhánh phiên
+
+Operator không bao giờ ghi lên nhánh mà người dùng đang checkout. Nó chỉ ghi trên
+`session/<sessionId>` của checkout được route, trong git worktree mà orchestrator đã dựng sẵn từ head
+đóng băng, và nó giữ một lease độc quyền trên worktree ấy suốt lúc ghi. Write set đã khai được commit
+đúng một lần; `response.json` mang đúng một sha đó trong `commits`, dòng Checkout của `changes.md` ghi
+`@workspaces/fe` ở head gốc rồi tới sha mới trên `session/<sessionId>`, và các request sau ghim
+`@workspaces/fe` ở sha đó. Ở đây không push và không merge: `git.publish` sở hữu cả hai việc ấy.
+
+## Không có giá trị tự nghĩ ra
+
+Mọi class mà lần ghi tạo ra đều đã có sẵn trong kho class của resolution được bind, và mọi identifier
+nó mang vào một lời khai đều đã có sẵn trong kho luật đã áp dụng. Cả hai danh sách đều đầy đủ và đóng
+băng. Một class không có trong resolution là `WRITE_REJECTED`: không làm tròn về giá trị gần, không
+chép từ file bên cạnh, không định dạng lại theo kiểu đổi mất một bước thang. Một file mà lần ghi sẽ
+chạm tới nhưng write set không khai cũng là `WRITE_REJECTED`, kể cả khi rõ ràng nó cần đổi; bước đúng
+tiếp theo là sửa write set, không phải ghi rộng ra. Một path đã khai mà gốc owner của nó không chứa là
+`OWNER_CONFLICT`, vì thuộc về owner nào chưa phải là trần. Phép kiểm kho chạy trên bản chiếu, trước
+khi ghi bất cứ thứ gì, nên một lần áp dụng bị từ chối để source y nguyên.
+
+## Node do ứng dụng sở hữu thành một file lá rỗng
+
+Khi hướng đánh dấu một node là do ứng dụng sở hữu, chẳng hạn một canvas, bản chiếu ghi ra một file lá
+rỗng mang contract của node đó, tức props và states của nó, để cây biên dịch được và bề mặt render ra
+đo được. Operator không bao giờ viết phần logic của file lá ấy: contract là thứ hướng đã quyết, còn
+hành vi phía sau nó thuộc về ai sở hữu node.
+
+## Không đổi là một phép đo
+
+Mọi path đã khai đều được băm trước bản chiếu và sau commit. Path có bản chiếu khác nội dung hiện tại
+thì được tạo hoặc sửa; path có bản chiếu bằng đúng nội dung hiện tại được ghi `unchanged`. Sau commit,
+cây được đọc lại và đối chiếu với cây đã resolve, và một chỗ lệch là `WRITE_REJECTED` chứ không phải
+một thành công lặng lẽ. Dưới `mode = dry` không có gì được ghi cả: nhánh phát ra bản kế hoạch trong
+`response/data/writes.json` với commit rỗng rồi dừng ở đó.
+
+## Ranh giới
+
+Operator ghi các path trong write set đã khai trên nhánh phiên của `@workspaces/fe`, mỗi path nằm
+dưới một gốc owner được sửa, và ghi `response/` của chính nó. Nó không ghi class, giá trị hay
+identifier vắng mặt trong resolution được bind, không quyết một giá trị trình bày, không chọn
+component Grammar, không dựng lại cây, không viết logic của file lá do ứng dụng sở hữu, không chạm
+file ngoài write set đã khai, không commit lên nhánh nào khác, không push, không merge, không sửa
+knowledge, không publish Grammar, không đổi resolution, không khởi động hay cấu hình lại dịch vụ
+runtime, và không ghi phán quyết, điểm số hay tuyên bố pass lên source đã áp dụng. Nó biết nó ghi gì,
+không bao giờ biết nó render ra sao.
+
+## Context
+
+| Alias | Bind | Bắt buộc |
+| --- | --- | --- |
+| `@workspaces/fe` | checkout frontend được route ở head đóng băng; lần ghi đáp xuống nhánh phiên của nó và không đâu khác | có |
+
+## Đầu vào
+
+| Kind | Từ đâu | Bắt buộc |
+| --- | --- | --- |
+| `frontend-presentation-resolution` | `frontend.presentation.resolve`, cây đã resolve và, ngay bên cạnh, kho class và kho luật đã đóng băng | có |
+| `frontend-direction-decision` | `frontend.direction.decide`, ý đồ và trần owner; không bao giờ là nguồn giá trị | có |
+
+## Yêu cầu
+
+| Field | Kiểu | Mặc định | Hỏi |
+| --- | --- | --- | --- |
+| `mode` | choice | apply | `apply` ghi rồi commit, `dry` chỉ phát bản kế hoạch và không ghi gì |
+| `resume` | token | null | Token của nhánh bị chặn khi vào lại sau một mã dừng |
+
+## Các bước
+
+| # | Bước | Tham số | Đọc | Ghi | Dừng với |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Kiểm gate, chạy lại, và xác nhận head | `resume`, `mode` | `request/request.json`, đầu vào `frontend-presentation-resolution`, @workspaces/fe ở head đóng băng | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Bind resolution, direction và write set đã khai | — | đầu vào `frontend-presentation-resolution` (fingerprint cây, kho class và kho luật, cây đã resolve) và `frontend-direction-decision` (ý đồ và trần owner), @workspaces/fe (các path đã khai và gốc owner của chúng) | — | `RESOLUTION_STALE`, `OWNER_CONFLICT` |
+| 3 | Chiếu cây đã resolve lên các path đã khai | — | đầu vào `frontend-presentation-resolution` (cây đã resolve), @workspaces/fe (write set đã khai) | — | — |
+| 4 | Đối chiếu mọi giá trị tạo ra với kho | `mode` | đầu vào `frontend-presentation-resolution` (kho nằm cạnh biên nhận) | `response/data/writes.json` | `WRITE_REJECTED` |
+| 5 | Ghi nguyên khối trên nhánh phiên và commit một lần | — | @workspaces/fe (nội dung hiện tại của từng path đã khai, dưới một lease độc quyền) | @workspaces/fe/branch/session, `response/data/writes.json`, @tools/sourcewrite, @tools/git, asset ảnh mà direction phán là cần, @tools/imagegen | — |
+| 6 | Đọc lại cây ở commit | — | @workspaces/fe ở commit | — | `WRITE_REJECTED` |
+| 7 | Phát | — | mọi thứ ở trên | `response/response.md`, `response/changes.md`, `response/response.json` | — |
+
+Dưới `mode = dry`, nhánh dừng sau bước 4 với riêng bản kế hoạch: `writes.json` mang commit rỗng,
+`response.json` không mang commit nào, và checkout y nguyên. Dưới `apply`, bước 5 ghi rồi commit đúng
+một lần và bước 6 chứng minh rằng cây đã commit đúng là cây đã resolve. `changes.md` là bản ghi mà
+các bước sau đọc: path nào đã dịch chuyển, chúng mang lời khai nào, checkout ghim cổng nào cho chúng,
+và bề mặt nào bây giờ phải được quan sát.
+
+## Đầu ra
+
+| Kind | File | Kiểu | Bắt buộc |
+| --- | --- | --- | --- |
+| `frontend-source-application` | `response/response.md` | md | có |
+| `changes` | `response/changes.md` | md | có |
+| `writes` | `response/data/writes.json` | data | có |
+
+## Dừng
+
+| Code | Xử lý |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `OWNER_CONFLICT` | terminate |
+| `RESOLUTION_STALE` | terminate |
+| `WRITE_REJECTED` | terminate |
+| `NO_PROGRESS` | terminate |
+
+## Kế tiếp
+
+| Khi | Operator |
+| --- | --- |
+| source đã commit và bề mặt render ra phải được đo | `frontend.surface.audit` |
+| source đã commit và các cổng của chính checkout phải chạy | `quality.verify` |