@troylar/flightdeck 2.12.2 → 2.14.0

package/bin/flightdeck.js

@@ -500,6 +500,9 @@ function loadEngine() {
    read, and named in skipped. */
 function readAdapter(root, opts) {
   const NOFOLLOW = fs.constants.O_NOFOLLOW || 0, links = [], skipped = [], max = (opts && opts.maxBytes) || 0;
+  /* vanished: a file or folder that was there when its path was walked and gone when it was opened (a sync or another program
+     moved it in between). The read gives nothing, as for a file that isn't there, and the path is named. */
+  const vanished = [], gone = (rel) => { if (vanished.indexOf(rel) < 0) vanished.push(rel); };
   function linkErr(rel) { const e = new Refused('refusing to read through a link: ' + rel); e.link = true; if (links.indexOf(rel) < 0) links.push(rel); return e; }
   function skipErr(rel, bytes, cap, more) {
     const e = new Refused(rel + ' is ' + (more ? 'more than ' : '') + size(bytes) + ', over the ' + size(cap) + ' this command reads');
@@ -562,7 +565,7 @@ function readAdapter(root, opts) {
     const f = fileAt(p);
     if (!f) return null;
     let fd;
-    try { fd = fs.openSync(f.full, fs.constants.O_RDONLY | NOFOLLOW); } catch (e) { if (e.code === 'ELOOP') throw linkErr(p); if (e.code === 'ENOENT') return null; throw e; }
+    try { fd = fs.openSync(f.full, fs.constants.O_RDONLY | NOFOLLOW); } catch (e) { if (e.code === 'ELOOP') throw linkErr(p); if (e.code === 'ENOENT') { gone(p); return null; } throw e; }
     try {
       const st = fs.fstatSync(fd), now = lstatOrNull(path.join(sameWalk(f.a, f.ids, p), f.name));
       if (!st.isFile() || st.ino !== f.st.ino || st.dev !== f.st.dev || !now || now.isSymbolicLink() || now.ino !== st.ino || now.dev !== st.dev) throw linkErr(p);
@@ -570,13 +573,13 @@ function readAdapter(root, opts) {
     } catch (e) { fs.closeSync(fd); throw e; }
   }
   return {
-    links, skipped,
+    links, skipped, vanished,
     list: (p) => new Promise((res) => {
       const a = partsOf(p), dir = dirAt(a);
       /* No such folder: empty, and marked missing, so a reader that saw it listed can tell gone from empty. */
       if (!dir) { const none = []; none.missing = true; return res(none); }
       let entries;
-      try { entries = fs.readdirSync(dir.cur, { withFileTypes: true }); } catch (e) { if (e.code !== 'ENOENT') throw e; const none = []; none.missing = true; return res(none); }
+      try { entries = fs.readdirSync(dir.cur, { withFileTypes: true }); } catch (e) { if (e.code !== 'ENOENT') throw e; gone(p || '.'); const none = []; none.missing = true; return res(none); }
       sameWalk(a, dir.ids, p || '.');
       res(entries.map((e) => {
         const rel = (p ? p + '/' : '') + e.name;
@@ -807,7 +810,8 @@ function folderProblems(PF, d) {
 }
 function adapterProblems(adapter) {
   return (adapter.links || []).map((p) => ({ path: p, kind: 'link', why: 'A link. Flightdeck never reads through links.' }))
-    .concat((adapter.skipped || []).map((x) => ({ path: x.path, kind: 'skipped', why: 'Too large to read here (' + (x.more ? 'more than ' : '') + size(x.size) + '; the limit is ' + size(x.cap) + ').' })));
+    .concat((adapter.skipped || []).map((x) => ({ path: x.path, kind: 'skipped', why: 'Too large to read here (' + (x.more ? 'more than ' : '') + size(x.size) + '; the limit is ' + size(x.cap) + ').' })))
+    .concat((adapter.vanished || []).map((p) => ({ path: p, kind: 'vanished', why: 'It was there a moment ago and was gone when it was read. Try again.' })));
 }
 
 /* What a whole-folder command's output depends on, as folders and files: its data, the publications that say whether a
@@ -1514,6 +1518,8 @@ async function draftState(eng, dir, proc, session) {
   try {
     const f = await rfs.read(dpath, { maxBytes: PF.util.DRAFT_BYTES });
     if (f) Object.assign(draft, { exists: true, rev: sha(f.text), text: f.text });
+    /* Gone between seeing it and opening it: there, but unread (named), so nothing takes it as absent. */
+    else if ((ra.vanished || []).indexOf(dpath) >= 0) { draft.exists = true; L.note(dpath, 'vanished', 'It was there a moment ago and was gone when it was read. Try again.'); }
   } catch (e) { draft.exists = true; }
   const copies = [];
   try {
@@ -1566,17 +1572,116 @@ function writeNew(dir, parts, text) {
   if (!fs.readFileSync(target).equals(data)) fail(target + ' didn\'t read back as written');
   return parts.join('/');
 }
+/* Everything Review & publish checks a draft's text against, read now through one problem ledger over a read-only view of
+   the folder, with the app's own readers: people.json, the team's step types, jira/workflows.json, every process's published
+   versions (which are published, the children linked steps start, the parents that start this one), the team values a
+   linked step names and the screenshots the text shows. Then PF.publish.checkContext and publishCheck, as the app's checks.
+   What couldn't be read (or a newer Flightdeck wrote) is a problem, which makes the answer partial, and that part is left
+   unchecked: it never becomes a blocker, a missing person or an unpublished process. Returns { verdict, problems }. */
+async function draftInputs(eng, dir, text) {
+  const PF = eng.PF, ra = readAdapter(dir, { maxBytes: READ_MAX }), L = PF.repo.ledger(PF.repo.readOnly(ra, 'Checking a draft'));
+  /* The ledger's problems and the adapter's (links, files too big, files that vanished), each once. */
+  const everything = () => { const out = L.problems(), seen = {}; out.forEach((x) => { seen[x.path + '\u0000' + x.kind] = true; }); adapterProblems(ra).forEach((x) => { if (!seen[x.path + '\u0000' + x.kind]) out.push(x); }); return out; };
+  /* A failure that stops the read at any stage (the team folder can't be listed) still names every problem met before it. */
+  try { return await readInputs(eng, text, ra, L, everything); } catch (e) { if (e && typeof e === 'object') e.problems = everything(); throw e; }
+}
+async function readInputs(eng, text, ra, L, everything) {
+  const PF = eng.PF, repo = PF.repo, M = PF.map, rfs = L.fs;
+  const map = M.parse(text), failedAt = (p) => L.problems().some((x) => x.path === p || x.path.indexOf(p + '/') === 0);
+  /* The app's own loader, limited to these parts: what each part's reader gives, or the part named in failed. */
+  const deps = [PF.people.FILE, 'step-types', 'jira/workflows.json', 'publications'];
+  const d = await repo.loadAll(dependsOn(rfs, deps), { readOnly: true, explain: true, deep: true });
+  const failed = d.failed || {};
+  /* First every read, with what each loader refused noted in the ledger; then the adapter's own problems (links, files too
+     big); then PF.publish.unknownOf decides what's unknown from that whole list, and nothing else does. */
+  const PARTS = { people: PF.people.FILE, 'step types': 'step-types', 'Jira workflows': 'jira/workflows.json', publications: 'publications' };
+  Object.keys(PARTS).forEach((k) => { if (k in failed && !failedAt(PARTS[k])) L.note(PARTS[k], /newer/.test(failed[k]) ? 'newer' : 'unreadable', failed[k]); });
+  const people = 'people' in failed ? null : d.people;
+  if (people && people.text != null && people.doc == null) L.note(PF.people.FILE, 'malformed', PF.people.FILE + ' isn\'t valid JSON.');
+  const types = 'step types' in failed ? {} : d.stepTypes.types;
+  if (!('step types' in failed)) {
+    (d.stepTypes.refused || []).forEach((r) => L.note(r.path, 'newer', r.why));
+  }
+  /* What a loader left out over its limit, from its own read (PF.publish.excludedOf): each named, and unknown below. */
+  PF.publish.excludedOf({ stepTypes: 'step types' in failed ? null : d.stepTypes, jira: 'Jira workflows' in failed ? null : d.jira }).forEach((x) => L.note(x.path, x.kind, x.why));
+  const processes = 'publications' in failed ? [] : d.processes.map((p) => {
+    /* A version that read but can't be used is named as READ names one; a failed read the ledger already has. */
+    p.pubs.filter((x) => !x.ok && !x._readFailed).forEach((x) => { const k = PF.appjson.pubProblem(x); L.note('publications/' + p.process + '/' + x.folder + '/', k.kind, k.why); });
+    return { id: p.process, latest: p.index.latest, all: p.index.all, clashes: p.index.clashes, broken: p.pubs.filter((x) => !x.ok) };
+  });
+  /* Team values (2.9), read only for a text that passes one, as publishing reads them. */
+  let teamValues;
+  if (M.steps(map).some((x) => x.step.type === 'run.process' && PF.links.teams(x.step).length)) {
+    teamValues = await repo.readTeamValues(rfs);
+    if (teamValues.state !== 'ok' && teamValues.state !== 'missing' && !failedAt(PF.teamValues.FILE)) L.note(PF.teamValues.FILE, teamValues.state, teamValues.why || PF.teamValues.FILE + ' couldn\'t be read.');
+  }
+  /* Screenshots, read to the last byte as publishing reads them: one that isn't there is a blocker. */
+  const shots = M.shotSources(map), missingShots = [];
+  for (const src of shots) {
+    try { const b = await rfs.blob(src); if (!b) missingShots.push(src); else await b.arrayBuffer(); } catch (e) { if (!failedAt(src)) L.note(src, 'unreadable', src + ' couldn\'t be read: ' + (e && e.message || String(e))); }
+  }
+  /* Only what the text uses counts: a problem with an input it doesn't use (a team-values.json link and no team: value)
+     leaves the answer complete. */
+  const used = PF.publish.usesOf(map), problems = everything().filter((x) => PF.publish.uses(used, x, shots));
+  const ctx = PF.publish.checkContext({ people, types, workflows: d.jira ? d.jira.workflows : null, processes, teamValues, missingShots, unknown: PF.publish.unknownOf(problems, shots) });
+  return { verdict: PF.publish.publishCheck(text, ctx), problems };
+}
+/* flightdeck draft check <team folder> <process> [--from <file | ->] --json (2.13): the verdict Review & publish gives the
+   draft in maps/drafts/ (or the text given with --from), from the folder as it is now (draftInputs). Read-only; prints
+   flightdeck-read/2 with SCHEMA2.draftCheck: exit 0, 4 when part of the folder couldn't be read, 5 when there's no draft,
+   1 for a usage problem or a draft that can't be read. */
+async function draftCheck(argv) {
+  const VAL = ['--from'], args = argv.filter((a, i) => !a.startsWith('--') && !(i > 0 && VAL.indexOf(argv[i - 1]) >= 0));
+  let eng = null;
+  const C2 = 2, appOf = () => (eng ? eng.version : versionOf(app()) || '');
+  const failOut = (kind, why, problems, code) => { const F = eng ? eng.PF.appjson : null, json = F ? F.failure(appOf(), kind, why, problems || [], C2) : { contract: 'flightdeck-read/2', app: appOf(), error: { kind, why }, problems: [] }; return { out: JSON.stringify(json, null, 2), code: code || EXIT.error }; };
+  const usage = (why) => failOut('usage', why);
+  const fi = argv.indexOf('--from'), from = fi >= 0 ? argv[fi + 1] : null;
+  if (fi >= 0 && (from == null || (from.startsWith('--') && from !== '-'))) return usage('say what goes after --from.');
+  const unknown = argv.filter((a) => a.startsWith('--') && ['--json', '--from'].indexOf(a) < 0);
+  if (unknown.length) return usage('draft check doesn\'t take ' + unknown.join(', ') + '.');
+  if (!argv.includes('--json')) return usage('flightdeck draft prints JSON. Add --json.');
+  const proc = args[3];
+  if (!args[2] || !proc || args[4] || !PROC_ID.test(proc)) return usage('say the team folder and a process ID (lowercase letters, numbers and dashes), for example: flightdeck draft check <team folder> release --json');
+  let dir;
+  try { eng = loadEngine(); dir = folderArg(args[2], 'draft check'); } catch (e) { return failOut('failed', e.message); }
+  const PF = eng.PF, A = PF.appjson;
+  let text, said;
+  if (from != null) {
+    const input = inputText(PF, from, 'the text');
+    if (input.why) return usage(input.why);
+    if (PF.proposals.textProcess(input.text) !== proc) return usage('the text\'s process: line must say ' + proc + '.');
+    text = input.text; said = { kind: 'file', ref: null };
+  } else {
+    const ra = readAdapter(dir, { maxBytes: READ_MAX }), L = PF.repo.ledger(PF.repo.readOnly(ra, 'Checking a draft')), dpath = 'maps/drafts/' + proc + '.md';
+    let f = null;
+    try { f = await L.fs.read(dpath, { maxBytes: PF.util.DRAFT_BYTES }); } catch (e) { return failOut('failed', dpath + ' couldn\'t be read, so nothing was checked. Try again.', L.problems().concat(adapterProblems(ra))); }
+    /* A draft that was there a moment ago and gone when opened is unknown, never "no draft". */
+    if (!f && (ra.vanished || []).indexOf(dpath) >= 0) return failOut('failed', dpath + ' was gone when it was read, so nothing was checked. Try again.', L.problems().concat(adapterProblems(ra)));
+    if (!f) return failOut('not-found', 'There\'s no draft for "' + proc + '" in this folder (' + dpath + '). Pass the text to check with --from.', [], EXIT.notFound);
+    text = f.text; said = { kind: 'draft', ref: dpath };
+  }
+  try {
+    const got = await draftInputs(eng, dir, text);
+    const data = { process: proc, from: { kind: said.kind, ref: said.ref, rev: PF.proposals.sha(text) }, checks: got.verdict.checks, publish: got.verdict.publish };
+    const e = A.envelope(eng.version, new Date().toISOString(), got.problems, data, C2);
+    return { out: JSON.stringify(e, null, 2), code: e.complete ? 0 : EXIT.partial };
+  } catch (e) {
+    return failOut('failed', e instanceof Refused ? e.message : 'The team folder couldn\'t be read: ' + (e && e.message || String(e)), e && e.problems);
+  }
+}
 async function draftMain(argv) {
   const VAL = ['--session', '--expect', '--from', '--base', '--label', '--by', '--note'], val = {};
   const args = argv.filter((a, i) => !a.startsWith('--') && !(i > 0 && VAL.indexOf(argv[i - 1]) >= 0));
   const sub = args[1], usage = (why) => draftFail(null, 'usage', why);
+  if (sub === 'check') return draftCheck(argv);
   for (const f of VAL) {
     const i = argv.indexOf(f);
     if (i < 0) continue;
     if (argv[i + 1] == null || (argv[i + 1].startsWith('--') && argv[i + 1] !== '-')) return usage('say what goes after ' + f + '.');
     val[f] = argv[i + 1];
   }
-  if (['read', 'save', 'propose'].indexOf(sub) < 0) return usage('say read, save or propose, for example: flightdeck draft read <team folder> <process> --json');
+  if (['read', 'save', 'propose'].indexOf(sub) < 0) return usage('say read, save, propose or check, for example: flightdeck draft read <team folder> <process> --json');
   if (!argv.includes('--json')) return usage('flightdeck draft prints JSON. Add --json.');
   const proc = args[3];
   if (!proc || !PROC_ID.test(proc)) return usage('a process ID is lowercase letters, numbers and dashes, for example: flightdeck draft ' + sub + ' <team folder> release --json');
@@ -1585,30 +1690,8 @@ async function draftMain(argv) {
   try { eng = loadEngine(); dir = folderArg(args[2], 'draft ' + sub); } catch (e) { return draftFail(eng, 'failed', e.message); }
   const PF = eng.PF, PP = PF.proposals, U = PF.util, M = PF.map, now = Date.now();
   const session = val['--session'] || 's-' + U.randomId(12);
-  /* The same checks the app shows, with each linked step's child read from publications/ (2.8), so what a step passes is
-     checked against the child as it is in the folder. */
-  const checksOf = async (t) => {
-    const map = M.parse(t), procs = {}, names = [];
-    M.steps(map).forEach((x) => { const f = x.step.fields || {}; if (x.step.type === 'run.process' && f.process && names.indexOf(f.process) < 0) names.push(f.process); });
-    /* The children are read through a problem ledger of their own, so a child that couldn't be read makes the answer partial. */
-    const L = PF.repo.ledger(readAdapter(dir, { maxBytes: READ_MAX })), rfs = L.fs;
-    for (const n of names) {
-      try {
-        const p = await PF.repo.readProcess(rfs, n);
-        if (p) procs[n] = p;
-        /* A version that read but can't be used is named as READ names one; a failed read the ledger already has. */
-        (p ? p.broken : []).forEach((x) => { if (!x._readFailed) { const k = PF.appjson.pubProblem(x); L.note('publications/' + n + '/' + x.folder + '/', k.kind, k.why); } });
-      } catch (e) { procs[n] = { latest: null, all: [], clashes: [], broken: [], unlisted: 'publications/' + n + '/ couldn\'t be read' }; }
-    }
-    /* Team values (2.9), through the same ledger: a failed read is noted by the ledger; damaged or newer content here. */
-    let tv;
-    if (M.steps(map).some((x) => x.step.type === 'run.process' && PF.links.teams(x.step).length)) {
-      tv = await PF.repo.readTeamValues(rfs);
-      if (tv.state === 'malformed' || tv.state === 'newer') L.note(PF.teamValues.FILE, tv.state, tv.why);
-    }
-    const c = M.check(map, { people: [], types: {}, workflows: {}, processes: [], children: PF.links.childrenFrom(procs), teamValues: tv });
-    return { checks: { blockers: c.blockers, suggestions: c.suggestions }, problems: L.problems() };
-  };
+  /* The same checks the app shows, on the folder as it is now (draftInputs), through the same functions. */
+  const checksOf = async (t) => { const got = await draftInputs(eng, dir, t); return { checks: got.verdict.checks, publish: got.verdict.publish, problems: got.problems }; };
   /* Every problem once: the draft's reads, then the children's. */
   const merged = (a, b) => { const seen = {}, out = []; a.concat(b).forEach((p) => { const k = p.path + '\u0000' + p.kind; if (!seen[k]) { seen[k] = true; out.push(p); } }); return out; };
   try {
@@ -1620,7 +1703,9 @@ async function draftMain(argv) {
       const cf = pending ? { rev: pending.rev, kind: 'proposal', ref: pending.id, text: pending.text }
         : s.draft.exists && s.draft.text != null ? { rev: s.draft.rev, kind: 'draft', ref: s.draft.path, text: s.draft.text }
           : latest ? { rev: latest.rev, kind: 'version', ref: latest.folder, text: latest.text } : { rev: PP.sha(''), kind: 'none', ref: null, text: '' };
-      const ck = await checksOf(cf.text), problems = merged(s.problems, ck.problems);
+      /* The draft is there but couldn't be read, and nothing else continues it: its text is unknown, so nothing is checked. */
+      const unread = !pending && s.draft.exists && s.draft.text == null;
+      const ck = unread ? { checks: { blockers: [], suggestions: [] }, problems: [] } : await checksOf(cf.text), problems = merged(s.problems, ck.problems);
       const out = draftJson(eng, { process: proc, session, draft: s.draft, openIn: s.presence.openIn, mine: s.mine.map((m) => ({ id: m.id, rev: m.rev, status: m.status, text: m.text })),
         continueFrom: cf, checks: ck.checks, copies: s.copies, readAt: new Date(now).toISOString(), complete: problems.length === 0, problems });
       return { out: JSON.stringify(out, null, 2), code: out.complete ? 0 : EXIT.partial };
@@ -1641,7 +1726,9 @@ async function draftMain(argv) {
     const base = PP.baseFor({ expect: val['--expect'], draft: s.draft, mine: s.mine, versions: s.versions, baseText, afterEarlier: argv.includes('--after-earlier') });
     if (base.missing) return draftFail(eng, 'missing-base', 'The text you started from isn\'t the draft, one of this session\'s proposals or a published version any more. Pass the text you read with --base, or read the draft again.');
     const operation = PP.newId(now, U.randomId(10)), at = new Date(now).toISOString();
-    const result = { process: proc, session, operation, outcome: null, why: null, link: base.link, rev: PP.sha(text), file: null, ids: PP.ids(base.text, text), checks: (await checksOf(text)).checks, warnings: [], history: null };
+    const result = { process: proc, session, operation, outcome: null, why: null, link: base.link, rev: PP.sha(text), file: null, ids: PP.ids(base.text, text), checks: null, warnings: [], history: null, complete: true, problems: [] };
+    const ck = await checksOf(text), problems = merged(s.problems, ck.problems);
+    Object.assign(result, { checks: ck.checks, complete: problems.length === 0, problems });
     if (result.ids.removed.length) result.warnings.push('This removes step or phase IDs: ' + result.ids.removed.join(', ') + '. Runs and skills that name them will need a look.');
     let why = sub === 'propose' ? 'asked' : s.presence.open ? 'open' : null;
     const draftNow = s.draft.exists ? s.draft.text : null, expectText = base.kind === 'none' || base.kind === 'version' ? null : base.text;
@@ -1684,10 +1771,646 @@ async function draftMain(argv) {
     Object.assign(result, { outcome: 'proposed', why });
     return { out: JSON.stringify(draftJson(eng, result), null, 2), code: 0 };
   } catch (e) {
-    return draftFail(eng, 'failed', e instanceof Refused ? e.message : 'The team folder couldn\'t be changed: ' + (e && e.message || String(e)));
+    return draftFail(eng, 'failed', e instanceof Refused ? e.message : 'The team folder couldn\'t be changed: ' + (e && e.message || String(e)), EXIT.error, e && e.problems);
   }
 }
 
+/* ---------- flightdeck type list | read | save (2.14): step types through a checked write ----------
+   type save compares the exact bytes it read (SHA-256), writes a complete temporary file beside the target, checks the
+   folder allows hard links, compares again (bytes, then the path still names that file, then a final listing for copies),
+   commits with one link (a new type) or one rename (a change), reads it back and records one history line. Like two
+   Flightdeck windows in different browsers, two saves at the same instant can replace one another without either being
+   told. It writes nothing but step-types/<id>.json, one history line and its own temporary files. */
+const WRITE_CONTRACT = 'flightdeck-write/1';
+const TYPE_INPUT_MAX = 262144, TYPE_READ_CAP = 1048576;
+const NO_LINKS = ['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EXDEV'];
+const BIG = { bigint: true };
+/* A test hook (FD._hooks), when one is set; its promise is awaited only where the caller awaits it. */
+function hook(name, ...a) { const h = _hooks[name]; return h ? h(...a) : undefined; }
+const thenable = (p) => !!p && typeof p.then === 'function';
+const errText = (e) => (e && e.code ? e.code + (e.message && e.message.indexOf(e.code) < 0 ? ': ' + e.message : '') : (e && e.message) || String(e));
+function lstatBig(p) { try { return fs.lstatSync(p, BIG); } catch (e) { if (e.code === 'ENOENT') return null; throw e; } }
+const sameNode = (a, b) => a.dev === b.dev && a.ino === b.ino;
+const sameMeta = (a, b) => sameNode(a, b) && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs;
+const sha256 = (b) => crypto.createHash('sha256').update(b).digest('hex');
+const relOf = (dir, full) => path.relative(dir, full).split(path.sep).join('/');
+/* One bounded read through a descriptor: opened without following a link or blocking (a FIFO swapped in can't hang it),
+   checked at once to be the regular file lstat saw (st), read in a loop into at most limit bytes, then stat'ed again (the
+   snapshot). opts.cap refuses a bigger file before reading. Every descriptor is closed; a close error is a failure too. */
+function readThrough(full, phase, limit, st, opts) {
+  hook('beforeOpen', full, phase);
+  let fd;
+  try { fd = fs.openSync(full, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0) | (fs.constants.O_NONBLOCK || 0)); }
+  catch (e) { return { fail: e.code === 'ENOENT' ? 'gone' : e.code === 'ELOOP' ? 'link' : 'error', why: errText(e), code: e.code || null }; }
+  let res;
+  try {
+    const first = fs.fstatSync(fd, BIG);
+    if (!first.isFile()) res = { fail: 'notfile', why: 'it isn\'t a regular file' };
+    else if (!sameNode(first, st)) res = { fail: 'moved', why: 'it was replaced as it was opened' };
+    else if (opts && opts.cap && first.size > BigInt(opts.cap)) res = { fail: 'oversized', size: Number(first.size) };
+    else {
+      const buf = Buffer.alloc(limit);
+      let total = 0;
+      while (total < limit) { const n = fs.readSync(fd, buf, total, limit - total, total); if (!n) break; total += n; hook('readChunk', full, phase, total); }
+      res = { first, snap: fs.fstatSync(fd, BIG), bytes: buf.subarray(0, total), filled: total >= limit };
+    }
+  } catch (e) { res = { fail: 'error', why: errText(e), code: e.code || null }; }
+  try { fs.closeSync(fd); } catch (e) { if (!res.fail) res = { fail: 'close', why: 'couldn\'t close ' + full + ' (' + errText(e) + ')' }; }
+  return res;
+}
+/* A file read whole, up to the read cap, with the path checked again after the read: { state: 'bytes', bytes } or missing,
+   link (a link or non-file at the path), unreadable, oversized or vanished, each with why. retry reads once more when the
+   file was replaced in between. listed: the name was in the folder's listing, so a file gone before its first lstat
+   vanished; it's missing only when nothing said it was there. unreadable carries the error's code. */
+function readWhole(home, name, phase, retry, listed) {
+  const full = path.join(home, name);
+  for (let n = 0; n < (retry ? 2 : 1); n++) {
+    let st;
+    try { st = lstatBig(full); } catch (e) { return { state: 'unreadable', why: errText(e), code: e.code || null }; }
+    if (!st) return n ? { state: 'vanished', why: 'it was removed while Flightdeck was reading it' } : listed ? { state: 'vanished', why: 'It was listed, then gone before it could be read. Try again.' } : { state: 'missing' };
+    if (st.isSymbolicLink() || !st.isFile()) return { state: 'link', why: st.isSymbolicLink() ? 'it\'s a link; Flightdeck never reads through one' : 'it isn\'t a file', folder: st.isDirectory() };
+    const r = readThrough(full, phase, TYPE_READ_CAP + 1, st, { cap: TYPE_READ_CAP });
+    if (r.fail === 'gone') return { state: 'vanished', why: 'It was there a moment ago and was gone when it was read. Try again.' };
+    if (r.fail === 'link') return { state: 'link', why: 'it\'s a link; Flightdeck never reads through one' };
+    if (r.fail === 'oversized' || (!r.fail && r.filled)) return { state: 'oversized', bytes: r.fail ? r.size : r.bytes.length, why: 'it\'s over the ' + size(TYPE_READ_CAP) + ' Flightdeck reads' };
+    if (r.fail === 'moved') continue;
+    if (r.fail === 'close') return { state: 'unreadable', close: true, why: r.why, code: null };
+    if (r.fail) return { state: 'unreadable', why: r.why, code: r.code || null };
+    if (!sameMeta(r.first, r.snap)) continue;
+    hook('afterSnapshot', full, phase);
+    let now;
+    try { now = lstatBig(full); } catch (e) { return { state: 'unreadable', why: errText(e), code: e.code || null }; }
+    if (!now) return { state: 'vanished', why: 'it was removed while Flightdeck was reading it' };
+    if (sameMeta(now, r.snap)) return { state: 'bytes', bytes: r.bytes };
+  }
+  return { state: 'vanished', why: 'it changed while Flightdeck was reading it, twice. Try again.' };
+}
+const IO_KIND = { unreadable: true, link: true, skipped: true, vanished: true };
+const utf8ok = (b) => { try { new TextDecoder('utf-8', { fatal: true }).decode(b); return true; } catch (e) { return false; } };
+/* A text file read through the ledger as the app reads it (UTF-8, bad bytes replaced, a byte-order mark dropped), with
+   the replacement named: { text, size } or null. */
+async function readText(L, p, max) {
+  const b = await L.fs.blob(p, { maxBytes: max });
+  if (!b) return null;
+  const bytes = Buffer.from(await b.arrayBuffer());
+  if (!utf8ok(bytes)) L.note(p, 'malformed', 'isn\'t valid UTF-8 text; Flightdeck reads it with the bad bytes replaced');
+  return { text: new TextDecoder('utf-8').decode(bytes), size: bytes.length };
+}
+/* How many lines of one history file PF.repo.loadEditHistory rejects, counted as it counts them (the newest TL.HIST.READ
+   lines looked at; too long, not JSON, or not an entry cleanEntry keeps). */
+function historyRejects(TL, text, name) {
+  const H = TL.HIST, lines = String(text).split('\n');
+  let n = 0, seen = 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    if (++seen > H.READ) continue;
+    if (line.length > H.LINE || TL.bytes(line) > H.LINE) { n++; continue; }
+    let ok = false;
+    try { ok = !!TL.cleanEntry(JSON.parse(line), name); } catch (e) { ok = false; }
+    if (!ok) n++;
+  }
+  return n;
+}
+/* The type commands' problem ledger: PF.repo.ledger over a read-only view of the team folder (PF.repo.readOnly), as the
+   --json commands read. A step type's exact bytes are read through descriptors (readWhole), and what fails there is noted
+   in it by path; drafts and history are read through its fs, so every listing or read that fails lands in it too.
+   problems(): the ledger's and the adapter's (links, files too big, files that vanished), each once. */
+function typeLedger(PF, dir, what) {
+  const ra = dir ? readAdapter(dir, { maxBytes: READ_MAX }) : null, L = PF.repo.ledger(ra ? PF.repo.readOnly(ra, what) : {});
+  const problems = () => {
+    const out = L.problems(), seen = {};
+    out.forEach((x) => { seen[x.path + '\u0000' + x.kind] = true; });
+    if (ra) adapterProblems(ra).forEach((x) => { const k = x.path + '\u0000' + x.kind; if (!seen[k]) { seen[k] = true; out.push(x); } });
+    return out;
+  };
+  return { fs: L.fs, note: L.note, problems };
+}
+const denied = (code) => code === 'EACCES' || code === 'EPERM';
+/* Why a save is held because something couldn't be read, with the next step that fits the failure: access for a denial, a
+   person for a file too big to compare, a sync only for a file that changed or vanished as it was read. */
+function heldWhy(rel, got) {
+  if (denied(got.code)) return 'Access to ' + rel + ' was denied. Ask the folder owner to check your access, then try again.';
+  if (got.state === 'oversized') return rel + ' is over the ' + size(TYPE_READ_CAP) + ' Flightdeck reads, so it\'s too big to check here. Ask a person to look at it in Flightdeck.';
+  if (got.state === 'vanished') return rel + ' changed or vanished while Flightdeck read it, which usually means it\'s syncing. Try again once it has synced.';
+  if (got.state === 'link') return rel + ' isn\'t a file Flightdeck reads: ' + bare(got.why) + '.';
+  return rel + ' couldn\'t be read (' + bare(got.why) + '). Check the folder, then try again.';
+}
+const bare = (t) => String(t || '').trim().replace(/[.!?]+$/, '');
+const UNLISTED = 'Flightdeck couldn\'t list step-types/. Whether this type exists is unknown. Check folder access before trying again.';
+/* step-types/ as listed now: every entry, and the regular .json files in the order the app's loader reads them. */
+function typeListing(home) {
+  const entries = fs.readdirSync(home, { withFileTypes: true });
+  const names = entries.map((e) => e.name), files = entries.filter((e) => e.isFile() && /\.json$/i.test(e.name)).map((e) => e.name).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  return { entries, names, files };
+}
+function loadPosition(files, name) {
+  const all = files.indexOf(name) >= 0 ? files : files.concat([name]).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  return all.indexOf(name) + 1;
+}
+/* What a step-type file is to the command (state: ok, malformed or newer, on its exact bytes) and to the app (usable: the
+   app's lenient decoding, then checkCustom and name = ID, as repo.loadStepTypes reads it). */
+function typeFile(PF, bytes, file) {
+  const T = PF.types, bom = bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf;
+  const text = new TextDecoder('utf-8').decode(bytes);
+  let utf8 = true;
+  try { new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch (e) { utf8 = false; }
+  const crlf = (text.match(/\r\n/g) || []).length, lf = (text.match(/\n/g) || []).length - crlf, cr = (text.match(/\r(?!\n)/g) || []).length;
+  const lineEndings = !crlf && !lf && !cr ? 'none' : crlf && !lf && !cr ? 'crlf' : lf && !crlf && !cr ? 'lf' : 'mixed';
+  const out = { bom, utf8, text, lineEndings, state: 'ok', def: null, appDef: null, errors: [], needs: null, usable: false, valid: false };
+  let o, parsed = true;
+  try { o = JSON.parse(text); } catch (e) { parsed = false; }
+  const object = parsed && !!o && typeof o === 'object' && !Array.isArray(o);
+  /* The app's view. */
+  if (parsed) {
+    let errs;
+    try { errs = T.checkCustom(o); } catch (e) { errs = ['couldn\'t be read as a step type']; }
+    if (!errs.length && file === o.id + '.json') { try { T.customType(o); out.usable = true; out.appDef = o; } catch (e) { out.usable = false; } }
+  }
+  /* The command's view. */
+  if (!parsed) return Object.assign(out, { state: 'malformed', errors: [utf8 ? 'isn\'t valid JSON' : 'isn\'t valid UTF-8 text'] });
+  if (!object) return Object.assign(out, { state: 'malformed', errors: ['must be a JSON object'] });
+  if (o.format != null || o.features != null) {
+    const env = PF.envelope.judge('flightdeck-step-type', o);
+    if (!env.ok && env.kind === 'newer') { let e1; try { e1 = T.checkCustom(o)[0]; } catch (e) { e1 = ''; } return Object.assign(out, { state: 'newer', needs: env.needs || null, errors: [e1 || 'It needs a newer Flightdeck.'] }); }
+  }
+  out.def = o;
+  let errs;
+  try { errs = T.checkCustom(o).slice(); } catch (e) { errs = ['couldn\'t be read as a step type']; }
+  if (!utf8) return Object.assign(out, { state: 'malformed', errors: ['isn\'t valid UTF-8 text'].concat(errs) });
+  if (errs.length) return Object.assign(out, { state: 'malformed', errors: errs });
+  if (file !== o.id + '.json') return Object.assign(out, { state: 'malformed', errors: ['the file name must be ' + o.id + '.json'] });
+  out.valid = true;
+  return out;
+}
+const STATE_KIND = { malformed: 'malformed', newer: 'newer', unreadable: 'unreadable', oversized: 'skipped', vanished: 'vanished', link: 'link' };
+/* One file as type read and type list report it, its problem noted in the ledger. unknown: why step-types/ couldn't be
+   listed (or reached), when it couldn't: the file is still read where it can be, but its position is unknown, and a file
+   not found then is unreadable, never missing. Only absence nothing contradicts gives rev "none". */
+function typeEntry(PF, L, home, file, files, phase, unknown) {
+  const rel = 'step-types/' + file, listed = !unknown && files.indexOf(file) >= 0, pos = listed ? files.indexOf(file) + 1 : null;
+  const got = home ? readWhole(home, file, phase, true, listed) : { state: 'missing' };
+  const e = { state: got.state, rev: null, bytes: null, bom: null, lineEndings: null, utf8: null, text: null, def: null, errors: [], needs: null, position: pos, selected: pos == null ? null : pos <= PF.save.LIMIT, usable: pos == null ? null : false };
+  if (got.state === 'missing' && unknown) { L.note(rel, 'unreadable', unknown); return Object.assign(e, { state: 'unreadable', errors: [unknown] }); }
+  if (got.state === 'missing') return Object.assign(e, { rev: 'none', position: null, selected: null, usable: null });
+  if (got.state !== 'bytes') {
+    L.note(rel, STATE_KIND[got.state], got.why);
+    return Object.assign(e, { bytes: got.state === 'oversized' ? got.bytes : null, errors: got.why ? [got.why] : [] });
+  }
+  const f = typeFile(PF, got.bytes, file);
+  Object.assign(e, { state: f.state, rev: sha256(got.bytes), bytes: got.bytes.length, bom: f.bom, lineEndings: f.lineEndings, utf8: f.utf8, text: f.text, def: f.state === 'newer' ? null : f.def, errors: f.errors, needs: f.needs });
+  if (pos != null) e.usable = e.selected && f.usable;
+  if (f.state !== 'ok') L.note(rel, STATE_KIND[f.state], f.errors[0] || '');
+  return e;
+}
+function typeFail(eng, kind, why) { return { out: JSON.stringify(eng.PF.appjson.failure(eng.version, kind, why, [], 2), null, 2), code: EXIT.error }; }
+async function typeRead(eng, argv, args) {
+  const PF = eng.PF, AJ = PF.appjson, T = PF.types, sub = args[1];
+  const extra = argv.filter((a) => a.startsWith('--') && a !== '--json');
+  if (extra.length) return typeFail(eng, 'usage', 'type ' + sub + ' doesn\'t take ' + extra[0] + '.');
+  if (!argv.includes('--json')) return typeFail(eng, 'usage', 'flightdeck type ' + sub + ' prints JSON. Add --json.');
+  const id = args[3];
+  if (sub === 'read' && (!id || !T.ID.test(id) || id.length > T.ID_MAX)) return typeFail(eng, 'usage', 'a step type ID is lowercase letters, numbers, dashes and dots, like deploy.check: flightdeck type read <team folder> <id> --json');
+  if (args.length > (sub === 'read' ? 4 : 3)) return typeFail(eng, 'usage', 'type ' + sub + ' takes ' + (sub === 'read' ? 'a team folder and an ID' : 'a team folder') + ', nothing else.');
+  let dir;
+  try { dir = folderArg(args[2], 'type ' + sub); } catch (e) { return typeFail(eng, 'failed', e.message); }
+  const L = typeLedger(PF, dir, 'Reading step types'), readAt = new Date().toISOString();
+  let home = null, unknown = null, listing = { names: [], files: [], entries: [] };
+  try { home = folders(dir, ['step-types'], false); } catch (e) { L.note('step-types', 'link', e.message); unknown = bare(e.message) + '. Whether this type exists is unknown.'; }
+  if (home) { try { listing = typeListing(home); } catch (e) { L.note('step-types', 'unreadable', 'couldn\'t be listed (' + errText(e) + ')'); unknown = UNLISTED; } }
+  const done = (data) => { const env = AJ.envelope(eng.version, readAt, L.problems(), data, 2); return { out: JSON.stringify(env, null, 2), code: env.complete ? 0 : EXIT.partial }; };
+  if (sub === 'read') {
+    const file = id + '.json', e = typeEntry(PF, L, home, file, listing.files, 'read', unknown);
+    return done({ type: Object.assign({ id, path: 'step-types/' + file }, e) });
+  }
+  const S = PF.save, rows = [], other = [];
+  for (const file of listing.files) {
+    const e = typeEntry(PF, L, home, file, listing.files, 'list', null);
+    /* A listed type it's a copy of first, else the name it would be a copy of (the original may be gone). */
+    const base = listing.names.filter((n) => n !== file && /\.json$/i.test(n) && S.copiesOf(n, [file]).length)[0] || S.copyBase(file);
+    rows.push({ file, id: e.def && typeof e.def.id === 'string' ? e.def.id : null, state: e.state, rev: e.rev, kind: 'file', position: e.position, selected: e.selected, usable: e.usable,
+      copyOf: base && /\.json$/i.test(base) && T.ID.test(base.slice(0, -5).toLowerCase()) ? base : null, errors: e.errors });
+  }
+  listing.entries.filter((x) => !x.isFile() && /\.json$/i.test(x.name)).sort((a, b) => (a.name < b.name ? -1 : 1)).forEach((x) => {
+    const link = x.isSymbolicLink();
+    L.note('step-types/' + x.name, link ? 'link' : 'unusable', link ? 'it\'s a link; Flightdeck never reads through one' : 'it isn\'t a file');
+    other.push({ file: x.name, id: null, state: 'link', rev: null, kind: link ? 'link' : 'folder', position: null, selected: null, usable: null, copyOf: null, errors: [] });
+  });
+  return done({ types: rows.concat(other), limit: S.LIMIT, count: listing.files.length });
+}
+/* T: the new bytes in an exclusive temporary file beside the target, written in full, flushed, closed and read back. The
+   name never ends in .json, so no loader, copy check or count sees it. */
+function tempBeside(home, name, data) {
+  const tmp = path.join(home, '.' + name + '.' + process.pid + '.' + crypto.randomBytes(6).toString('hex') + '.tmp');
+  let fd = null, ours = null;
+  try {
+    fd = fs.openSync(tmp, 'wx');
+    ours = fs.fstatSync(fd, BIG);
+    for (let off = 0; off < data.length;) { const n = fs.writeSync(fd, data, off, data.length - off); if (!(n > 0)) throw new Error('the disk accepted no more bytes'); off += n; }
+    fs.fsyncSync(fd);
+    const c = fd; fd = null;
+    try { fs.closeSync(c); } catch (e) { throw new Error('couldn\'t close ' + tmp + ' (' + errText(e) + ')'); }
+    const back = readThrough(tmp, 'T', data.length + 1, ours, null);
+    if (back.fail) throw new Error('the temporary file couldn\'t be read back (' + back.why + ')');
+    if (back.filled || !back.bytes.equals(data)) throw new Error('the temporary file didn\'t read back as written');
+    return { tmp, ours };
+  } catch (e) {
+    if (fd !== null) try { fs.closeSync(fd); } catch (err) { /* the write already failed */ }
+    const x = new Error('couldn\'t write the new file (' + errText(e) + ')');
+    x.tmp = ours ? tmp : null; x.ours = ours;
+    throw x;
+  }
+}
+/* Remove a temporary file, only while it's still the one this process made. Returns the error, or null. */
+function removeOurs(full, ours, atUnlink) {
+  try {
+    const st = lstatBig(full);
+    if (!st || st.isSymbolicLink() || !sameNode(st, ours)) return null;
+    if (atUnlink) hook('atUnlink', full);
+    fs.unlinkSync(full);
+    return null;
+  } catch (e) { return errText(e); }
+}
+/* P: link the temporary file to a second name and remove it, before the target is touched. */
+function probeLinks(tmp) {
+  const probe = tmp.replace(/\.tmp$/, '.probe');
+  try { fs.linkSync(tmp, probe); } catch (e) { return NO_LINKS.indexOf(e.code) >= 0 ? { refused: 'no-links', why: errText(e) } : { failed: true, why: errText(e) }; }
+  try { fs.unlinkSync(probe); } catch (e) { return { failed: true, why: 'the check\'s second name couldn\'t be removed (' + errText(e) + ')', left: probe }; }
+  return null;
+}
+/* A new file, created once (the history line): T, P, then one link that never replaces anything. */
+function createOnce(dir, parts, data) {
+  const res = { commit: 'no', why: null, left: [], leftWhy: [] };
+  let home, t;
+  try { home = folders(dir, parts.slice(0, -1), true); } catch (e) { res.why = e.message; return res; }
+  const target = path.join(home, parts[parts.length - 1]);
+  try { t = tempBeside(home, parts[parts.length - 1], data); } catch (e) { res.why = e.message; if (e.tmp) { const w = removeOurs(e.tmp, e.ours); if (w) { res.left.push(e.tmp); res.leftWhy.push(w); } } return res; }
+  const p = probeLinks(t.tmp);
+  if (p) { res.why = p.why; if (p.left) { res.left.push(p.left); res.leftWhy.push(p.why); } }
+  else {
+    try {
+      if (lstatBig(target)) res.why = 'it\'s already there';
+      else { fs.linkSync(t.tmp, target); res.commit = 'yes'; }
+    } catch (e) { if (e.code === 'EEXIST') res.why = 'it\'s already there'; else { res.commit = 'unknown'; res.why = errText(e); } }
+  }
+  const w = removeOurs(t.tmp, t.ours);
+  if (w) { res.left.push(t.tmp); res.leftWhy.push(w); }
+  return res;
+}
+/* B: does the path still name our file, holding our bytes, unchanged while it was read? (design 1.4b) */
+function observeOther(target) {
+  try {
+    const st = lstatBig(target);
+    if (!st) return { now: null, kind: 'vanished', why: 'it was gone when Flightdeck looked at what replaced it' };
+    if (st.isSymbolicLink() || !st.isFile()) return { now: null, kind: 'link', why: 'a folder or a link is there now' };
+    const r = readThrough(target, 'observe', TYPE_READ_CAP + 1, st, { cap: TYPE_READ_CAP });
+    if (r.fail === 'oversized' || (!r.fail && r.filled)) return { now: null, kind: 'skipped', why: 'what replaced it is over the ' + size(TYPE_READ_CAP) + ' Flightdeck reads' };
+    if (r.fail === 'gone' || r.fail === 'moved') return { now: null, kind: 'vanished', why: 'what replaced it changed again as it was read' };
+    if (r.fail) return { now: null, kind: r.fail === 'link' || r.fail === 'notfile' ? 'link' : 'unreadable', why: r.why };
+    const fin = lstatBig(target);
+    if (!sameMeta(r.first, r.snap) || !fin || !sameMeta(fin, r.snap)) return { now: null, kind: 'vanished', why: 'it changed while Flightdeck was reading it' };
+    return { now: sha256(r.bytes), kind: null, why: null };
+  } catch (e) { return { now: null, kind: 'unreadable', why: errText(e) }; }
+}
+function readBack(target, ours, data) {
+  let st;
+  try { st = lstatBig(target); } catch (e) { return { back: 'unreadable', now: null, kind: 'unreadable', why: errText(e) }; }
+  if (!st) return { back: 'missing', now: null, why: null };
+  if (st.isSymbolicLink() || !st.isFile()) return { back: 'unreadable', now: null, kind: 'link', why: 'a folder or a link is there now' };
+  if (!sameNode(st, ours)) return Object.assign({ back: 'other' }, observeOther(target));
+  const r = readThrough(target, 'B', data.length + 1, st, null);
+  if (r.fail === 'gone') return { back: 'missing', now: null, why: null };
+  if (r.fail === 'moved') return Object.assign({ back: 'other' }, observeOther(target));
+  if (r.fail) return { back: 'unreadable', now: null, kind: 'unreadable', why: r.why };
+  hook('afterSnapshot', target, 'B');
+  let fin;
+  try { fin = lstatBig(target); } catch (e) { return { back: 'unreadable', now: null, kind: 'unreadable', why: errText(e) }; }
+  if (!fin) return { back: 'missing', now: null, why: null };
+  if (!sameNode(fin, ours)) return Object.assign({ back: 'other' }, observeOther(target));
+  const len = BigInt(data.length), stable = sameMeta(r.first, r.snap) && sameMeta(fin, r.snap);
+  if (r.filled || !r.bytes.equals(data) || r.snap.size !== len || fin.size !== len) return stable ? Object.assign({ back: 'other' }, observeOther(target)) : { back: 'other', now: null, kind: 'vanished', why: 'it changed while Flightdeck was reading it back' };
+  if (!stable) return { back: 'unstable', now: null, kind: 'vanished', why: 'it changed while Flightdeck was reading it back' };
+  return { back: 'same', now: sha256(data), why: null };
+}
+/* --from's bytes, never more than limit + 1 read (design D5): standard input (-), or a regular file opened without
+   blocking (a FIFO or a device is refused, never waited on or read without end). { bytes, over, size } or { usage }. */
+function boundedInput(file, limit) {
+  let fd = 0, own = false, size = null;
+  try {
+    if (file !== '-') {
+      fd = fs.openSync(expand(file), fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK || 0)); own = true;
+      const st = fs.fstatSync(fd);
+      if (!st.isFile()) return { usage: '--from is a file with the definition, or - for standard input; ' + file + ' isn\'t a regular file.' };
+      if (st.size > limit) return { bytes: null, over: true, size: st.size };
+    }
+    const buf = Buffer.alloc(limit + 1);
+    let total = 0, waits = 0;
+    while (total < buf.length) {
+      let n;
+      try { n = fs.readSync(fd, buf, total, buf.length - total, own ? total : null); } catch (e) {
+        if (e.code === 'EAGAIN' && !own && waits++ < 6000) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10); continue; }
+        if (e.code === 'EOF') break;
+        throw e;
+      }
+      if (!n) break;
+      total += n;
+    }
+    if (total > limit) return { bytes: null, over: true, size };
+    return { bytes: buf.subarray(0, total), over: false, size: total };
+  } catch (e) { return { usage: 'couldn\'t read --from (' + errText(e) + ').' }; }
+  finally { if (own) try { fs.closeSync(fd); } catch (e) { /* only read */ } }
+}
+/* The new definition from --from: at most 256 KB of strict UTF-8 (a leading byte-order mark dropped), no key twice in one
+   object, no __proto__, constructor or prototype key, one JSON object, the ID it's saved as, checkCustom, then formatWhy. */
+function typeInput(PF, file, id) {
+  const T = PF.types, S = PF.save;
+  const bad = (why, errors) => ({ invalid: why, errors: errors || [why] });
+  const got = boundedInput(file, TYPE_INPUT_MAX);
+  if (got.usage) return { usage: got.usage };
+  const buf = got.bytes;
+  if (got.over) return bad('the definition is ' + (got.size != null ? got.size + ' bytes' : 'more than ' + TYPE_INPUT_MAX + ' bytes') + '; a step type is at most ' + TYPE_INPUT_MAX + ' bytes (256 KB) of UTF-8');
+  let text;
+  try { text = new TextDecoder('utf-8', { fatal: true }).decode(buf); } catch (e) { return bad('the definition isn\'t valid UTF-8 text'); }
+  let def;
+  try { def = JSON.parse(text); } catch (e) { return bad('the definition isn\'t valid JSON (' + e.message + ')'); }
+  if (!def || typeof def !== 'object' || Array.isArray(def)) return bad('must be a JSON object');
+  const dup = S.duplicateKeys(text);
+  if (dup !== null) return bad('"' + dup + '" appears twice in one object; JSON keeps only the last, so say it once');
+  if (def.id !== id) return { usage: 'the definition\'s "id" must be ' + id + ', the ID it\'s saved as.' };
+  /* checkCustom first, so a reserved name gets the reader's own words (a shared rule); then the keys it doesn't look at. A
+     value the checks can't even read (a name that's an object with no usable text, say) is invalid too, never a crash. */
+  let data;
+  try {
+    const errs = T.checkCustom(def).slice();
+    if (errs.length) return bad(errs[0], errs);
+    const odd = S.oddKeys(def);
+    if (odd !== null) return bad('"' + odd + '" can\'t be a key in a step type');
+    const fw = T.formatWhy(def);
+    if (fw) return bad(fw);
+    data = Buffer.from(T.fileText(def), 'utf8');
+  } catch (e) { return bad('it couldn\'t be read as a step type: a name, label or option isn\'t plain text or a list where one is expected'); }
+  if (data.length > TYPE_INPUT_MAX) return bad('the saved file would be ' + data.length + ' bytes; a step type is at most ' + TYPE_INPUT_MAX + ' bytes (256 KB)');
+  return { def, data };
+}
+/* A flightdeck-write/1 answer with nothing done yet: every field, written false. */
+function writeShell(app, rel, outcome, error, words, now) {
+  return { contract: WRITE_CONTRACT, app, command: 'type save', path: rel, operation: null, outcome, written: false,
+    rev: { expected: null, before: null, after: null, now: null }, back: null, load: null, existing: null, appLoads: null,
+    checks: { errors: [], warnings: [], omitted: { before: null, after: null } }, askedBy: null, history: null, cleanup: null, error, words, readAt: new Date(now || Date.now()).toISOString(), complete: true, problems: [] };
+}
+async function typeSave(eng, argv, args, val) {
+  const PF = eng.PF, S = PF.save, T = PF.types, U = PF.util, TL = PF.timeline, now = Date.now();
+  const id = args[3], name = id + '.json', rel = 'step-types/' + name, idOk = !!id && T.ID.test(id) && id.length <= T.ID_MAX;
+  const out = writeShell(eng.version || '', idOk ? rel : null, '', null, '', now);
+  const left = [], leftWhy = [];
+  let dir = null, L = typeLedger(PF, null);
+  /* Every answer goes through PF.save.settle and PF.save.words. */
+  const finish = (f) => {
+    if (dir && left.length) out.cleanup = { leftover: left.map((p) => relOf(dir, p)), why: leftWhy.join('; ') };
+    const s = S.settle({ refused: f.refused || null, commit: f.commit || 'no', back: f.back || null, history: f.history || null, cleanup: out.cleanup, load: out.load });
+    out.outcome = s.outcome; out.written = s.written; out.back = s.back;
+    if (s.history) out.history = { path: f.historyPath, written: s.history.written, why: s.history.why };
+    const why = f.refused ? f.refused.why || '' : f.why || '';
+    out.words = S.words(s.outcome, { kind: s.kind, path: rel, why, copies: f.refused && f.refused.copies, needs: f.refused && f.refused.needs, load: out.load, history: s.history, cleanup: out.cleanup, back: s.back, dryRun: s.outcome === 'checked' });
+    out.error = s.kind ? { kind: s.kind, why: why || out.words } : null;
+    out.problems = L.problems(); out.complete = out.problems.length === 0;
+    return { out: JSON.stringify(out, null, 2), code: s.exit };
+  };
+  const refuse = (outcome, kind, why, more) => finish({ refused: Object.assign({ outcome, kind, why }, more || {}) });
+  const usage = (why) => refuse('refused', 'usage', why);
+  /* Flags first: nothing is read before every one checks out. */
+  const VAL = ['--expect', '--from', '--asked-by', '--note'], FLAGS = ['--json', '--dry-run'];
+  for (let i = 0; i < argv.length; i++) {
+    if (VAL.indexOf(argv[i]) >= 0) { i++; continue; }
+    if (argv[i].startsWith('--') && FLAGS.indexOf(argv[i]) < 0) return usage('type save doesn\'t take ' + argv[i] + '.');
+  }
+  if (!argv.includes('--json')) return usage('flightdeck type save prints JSON. Add --json.');
+  if (!idOk) return usage('a step type ID is lowercase letters, numbers, dashes and dots, like deploy.check: flightdeck type save <team folder> <id> --expect <rev|none> --from <file> --json');
+  if (args.length > 4) return usage('type save takes a team folder and an ID, nothing else.');
+  for (const f of VAL) if (argv.filter((a) => a === f).length > 1) return usage('say ' + f + ' once.');
+  for (const f of VAL) if (argv.indexOf(f) >= 0 && val[f] == null) return usage('say what goes after ' + f + '.');
+  const expect = val['--expect'];
+  if (expect == null || !(expect === 'none' || /^[0-9a-f]{64}$/.test(expect))) return usage('--expect is the rev type read gave (a SHA-256), or exactly none when type read said missing.');
+  out.rev.expected = expect;
+  if (val['--from'] == null) return usage('say where the definition is: --from <file>, or --from - to read it from standard input.');
+  const by = val['--asked-by'];
+  if (by != null && (by.length < 1 || by.length > 80 || /[\u0000-\u001f\u007f]/.test(by))) return usage('--asked-by is a person ID from people.json, like person-avery: 1 to 80 characters, no control characters.');
+  if (val['--note'] != null && val['--note'].length > 200) return usage('--note is at most 200 characters.');
+  const input = typeInput(PF, val['--from'], id);
+  if (input.usage) return usage(input.usage);
+  if (input.invalid) { out.checks.errors = input.errors; return refuse('refused', 'invalid', input.invalid); }
+  const def = input.def, data = input.data, dryRun = argv.includes('--dry-run');
+  out.rev.after = sha256(data);
+  try { dir = folderArg(args[2], 'type save'); } catch (e) { return refuse('failed', 'failed', e.message); }
+  L = typeLedger(PF, dir, 'Saving a step type');
+  out.operation = PF.proposals.newId(now, U.randomId(10));
+  const historyPath = 'history/step-types/' + id + '/agent-' + out.operation + '.jsonl';
+  try {
+    /* R1: the listing, the target's exact bytes, and who asked. */
+    let home;
+    try { home = folders(dir, ['step-types'], false); } catch (e) { L.note('step-types', 'link', e.message); return refuse('failed', 'failed', e.message); }
+    let listing = { names: [], files: [], entries: [] }, unlisted = null;
+    if (home) {
+      try { listing = typeListing(home); } catch (e) {
+        unlisted = denied(e.code) ? heldWhy('step-types/', { code: e.code }) : 'Flightdeck couldn\'t list step-types/ (' + errText(e) + '), so whether this type exists is unknown. Check folder access before trying again.';
+        L.note('step-types', 'unreadable', 'couldn\'t be listed (' + errText(e) + ')');
+      }
+    }
+    const got = home ? readWhole(home, name, 'R1', false, !unlisted && listing.files.indexOf(name) >= 0) : { state: 'missing' };
+    let seen, file = null, seenBytes = null;
+    if (got.state === 'link') { L.note(rel, 'link', got.why); return refuse('failed', 'failed', rel + ' isn\'t a file Flightdeck can save over: ' + got.why + '.'); }
+    /* A descriptor that won't close before the commit is a failure, never a hold (design 1.4). */
+    if (got.close) { L.note(rel, 'unreadable', got.why); return refuse('failed', 'failed', got.why); }
+    if (got.state === 'missing') { seen = { state: 'missing', rev: null }; out.existing = 'missing'; }
+    else if (got.state === 'bytes') {
+      seenBytes = got.bytes; file = typeFile(PF, got.bytes, name);
+      seen = { state: 'bytes', rev: sha256(got.bytes) }; out.rev.before = seen.rev; out.existing = file.state;
+      /* What's there is named whatever happens next: a malformed file this save repairs, or a newer one it refuses. */
+      if (file.state !== 'ok') L.note(rel, STATE_KIND[file.state], file.errors[0] || '');
+      const pos = listing.files.indexOf(name) >= 0 ? listing.files.indexOf(name) + 1 : null;
+      out.appLoads = pos != null && pos <= S.LIMIT && file.usable;
+    } else {
+      L.note(rel, STATE_KIND[got.state], got.why);
+      seen = { state: 'unreadable', rev: null, why: heldWhy(rel, got) };
+    }
+    const asked = { required: false, held: '', verdict: '' };
+    if (by != null) {
+      /* Listed at the top of the folder first, so a people.json gone as it's read is held, never taken as no people. */
+      let top = null, topWhy = null;
+      try { top = fs.readdirSync(dir); } catch (e) { topWhy = e; }
+      const p = topWhy ? null : readWhole(dir, 'people.json', 'people', false, top.indexOf('people.json') >= 0);
+      if (topWhy) {
+        L.note('people.json', 'unreadable', 'the team folder couldn\'t be listed (' + errText(topWhy) + '), so whether people.json is there is unknown');
+        asked.held = 'Who asked can\'t be checked. ' + (denied(topWhy.code) ? heldWhy('the team folder', { code: topWhy.code }) : 'Flightdeck couldn\'t list the team folder (' + errText(topWhy) + '). Check folder access before trying again.');
+      } else if (p.close) { L.note('people.json', 'unreadable', p.why); return refuse('failed', 'failed', p.why); }
+      else if (p.state === 'missing') asked.verdict = S.asked([], by, 'person');
+      else if (p.state !== 'bytes') { L.note('people.json', STATE_KIND[p.state], p.why); asked.held = 'Who asked can\'t be checked. ' + heldWhy('people.json', p); }
+      else {
+        let doc;
+        try { doc = JSON.parse(new TextDecoder('utf-8').decode(p.bytes)); } catch (e) { doc = undefined; }
+        if (doc === undefined) { L.note('people.json', 'malformed', 'isn\'t valid JSON'); asked.held = 'people.json isn\'t valid JSON, so who asked can\'t be checked.'; }
+        else if (!PF.people.verdict(doc).ok) { L.note('people.json', 'newer', PF.people.verdict(doc).why); asked.held = 'people.json was made with a newer Flightdeck, so who asked can\'t be checked.'; }
+        else {
+          /* What reading it drops or changes is named as the reading commands name it: bad bytes replaced, entries without
+             a text ID and name, names cut to 60. */
+          if (!utf8ok(p.bytes)) L.note('people.json', 'malformed', 'isn\'t valid UTF-8 text; Flightdeck reads it with the bad bytes replaced');
+          const pw = peopleWhy({ hash: '', doc });
+          if (pw) L.note('people.json', 'malformed', pw);
+          const people = PF.people.clean(doc);
+          asked.verdict = S.asked(people, by, 'person');
+          if (!asked.verdict) { const me = people.filter((x) => x.id === by)[0]; out.askedBy = { id: by, name: me.name }; }
+        }
+      }
+    }
+    { const p = hook('afterRead', home ? path.join(home, name) : path.join(dir, 'step-types', name)); if (thenable(p)) await p; }
+    /* Warnings, never refusals; the history line built before any file is made (design 1.6). */
+    const W = out.checks.warnings, oldDef = file && file.state === 'ok' ? file.def : null;
+    /* What the app loads now (a malformed file it still reads leniently included) is what drafts depend on; oldDef, only a
+       valid file, is what history keeps. */
+    const depDef = oldDef || (file && file.usable ? file.appDef : null);
+    if (file && file.state === 'malformed') W.push(rel + ' is malformed (' + (file.errors[0] || 'it isn\'t a step type Flightdeck can use') + '); this save repairs it.');
+    T.unusedKeys(def).forEach((k) => W.push(k + ' isn\'t part of a step type Flightdeck reads; its editor drops it on its next save.'));
+    if (T.markerWhy(def)) W.push(T.markerWhy(def));
+    /* Drafts are read only when the change removes a field or evidence, through the ledger: a listing or a draft that
+       fails is a problem, and the warnings say the check is incomplete. */
+    const gone = T.removed(depDef, def), under = (d) => L.problems().some((x) => x.path === d || x.path.indexOf(d + '/') === 0);
+    if (depDef && (gone.fields.length || gone.evidence.length)) {
+      const drafts = [], DD = 'maps/drafts';
+      let items = [];
+      try { items = await L.fs.list(DD); } catch (e) { items = []; /* named in the ledger */ }
+      for (const i of items) {
+        if (i.kind !== 'file' || !/\.md$/i.test(i.name)) continue;
+        try { const f = await readText(L, DD + '/' + i.name, U.DRAFT_BYTES); if (f) drafts.push({ process: i.name.replace(/\.md$/i, ''), text: f.text }); } catch (e) { /* named in the ledger */ }
+      }
+      T.inUse(depDef, def, drafts).forEach((w) => W.push(w));
+      if (L.problems().some((x) => IO_KIND[x.kind] && (x.path === DD || x.path.indexOf(DD + '/') === 0))) W.push('Couldn\'t check drafts in maps/drafts/. Check them for uses of the removed fields before calling this change complete.');
+    }
+    const omitted = out.checks.omitted, appText = seenBytes ? new TextDecoder('utf-8').decode(seenBytes) : null, from = appText == null ? null : U.hash(appText);
+    if (file && file.state !== 'ok') omitted.before = 'invalid';
+    let seenId = null;
+    if (from) {
+      const HD = 'history/step-types/' + id;
+      /* Every file the reader reads is kept, so a line it rejects (not JSON, too long, a newer kind) is named by its file. */
+      const texts = {}, hfs = Object.assign({}, L.fs, { read: (p2, o) => readText(L, p2, (o && o.maxBytes) || READ_MAX).then((f) => { if (f) texts[p2] = f.text; return f; }) });
+      try {
+        const h = await PF.repo.loadEditHistory(hfs, HD, from); const e = h.items.filter((x) => x.entry && x.entry.to === from)[0]; seenId = e ? e.entry.id : null;
+        if (h.bad) Object.keys(texts).sort().forEach((p2) => { const n = historyRejects(TL, texts[p2], path.posix.basename(p2)); if (n) L.note(p2, 'malformed', n + ' line' + (n === 1 ? '' : 's') + ' Flightdeck couldn\'t read (not a history line, too long, or from a newer Flightdeck)'); });
+        if (h.skipped) L.note(HD, 'skipped', 'over the newest ' + TL.HIST.READ + ' lines Flightdeck reads; ' + h.skipped + ' older line' + (h.skipped === 1 ? ' wasn\'t' : 's weren\'t') + ' read');
+      } catch (e) { seenId = null; /* named in the ledger */ }
+      if (under(HD)) W.push('Couldn\'t read ' + HD + '/, so this save\'s history line doesn\'t say which earlier save it follows.');
+    }
+    const lineOf = (b, a) => TL.histLine({ kind: 'type-edit', id: out.operation, type: id, writer: out.operation, seq: 1, by: by || '', at: new Date(now).toISOString(), from, to: U.hash(T.fileText(def)), seen: seenId,
+      before: b, after: a, source: 'agent', units: [val['--note'] || 'Changed by your AI assistant'] });
+    let line = null, lineWhy = null;
+    try {
+      line = lineOf(oldDef, def);
+      if (line.big) { if (oldDef) omitted.before = 'cap'; omitted.after = 'cap'; }
+      else {
+        const c = TL.cleanEntry(JSON.parse(JSON.stringify(line)), 'agent-' + out.operation + '.jsonl');
+        if (oldDef && (!c || c.before == null)) omitted.before = 'cleaned';
+        if (!c || c.after == null) omitted.after = 'cleaned';
+      }
+    } catch (e) {
+      try { line = lineOf(null, null); if (oldDef) omitted.before = 'fallback'; omitted.after = 'fallback'; } catch (e2) { line = null; lineWhy = 'its history line couldn\'t be built (' + errText(e2) + ')'; omitted.after = 'fallback'; }
+    }
+    S.historyWarnings(omitted).forEach((w) => W.push(w));
+    /* J: one verdict. */
+    const v = S.judge({ mode: S.MODE, expect, seen, listing: unlisted ? { unlisted: true, why: unlisted } : listing.names, name, existing: file ? { verdict: file.state, needs: file.needs } : null, asked: { required: false, held: asked.held, verdict: asked.verdict }, newRev: out.rev.after, dryRun });
+    const loadIf = (files, from2) => { const position = loadPosition(files, name); out.load = { position, limit: S.LIMIT, selected: position <= S.LIMIT, from: from2 }; if (position > S.LIMIT) W.push(from2 === 'C' ? 'Flightdeck won\'t load it: it reads only the first ' + S.LIMIT + ' step-type files by name, and this is number ' + position + '.' : 'If saved with these files present, it would be number ' + position + ', and Flightdeck wouldn\'t load it: it reads only the first ' + S.LIMIT + ' by name.'); };
+    if (!v.go && v.outcome !== 'checked') return finish({ refused: { outcome: v.outcome, kind: v.kind, why: v.why, copies: (v.copies || []).map((c) => 'step-types/' + c), needs: v.needs } });
+    if (!line) return refuse('failed', 'failed', lineWhy);
+    if (v.outcome === 'checked') { loadIf(listing.files, 'R1'); return finish({ refused: { outcome: 'checked', kind: null, why: '' } }); }
+    /* T and P. */
+    let where, t;
+    /* step-types/ is made only for the save: a refusal or failure before the commit removes it again when this call made
+       it and it's still empty, so nothing is left behind (a temporary file it couldn't remove keeps it, and is named). */
+    const made = !lstatOrNull(path.join(dir, 'step-types'));
+    try { where = folders(dir, ['step-types'], true); } catch (e) { L.note('step-types', 'link', e.message); return refuse('failed', 'failed', e.message); }
+    const unmake = () => { if (!made) return; try { if (!fs.readdirSync(where).length) fs.rmdirSync(where); } catch (e) { /* not empty or gone: left as it is */ } };
+    const target = path.join(where, name);
+    try { t = tempBeside(where, name, data); } catch (e) { if (e.tmp) { const w = removeOurs(e.tmp, e.ours); if (w) { left.push(e.tmp); leftWhy.push(w); } } unmake(); return refuse('failed', 'failed', e.message); }
+    const clean = () => { const w = removeOurs(t.tmp, t.ours); if (w) { left.push(t.tmp); leftWhy.push(w); } unmake(); };
+    const stop = (outcome, kind, why, more) => { clean(); return refuse(outcome, kind, why, more); };
+    /* A read in the final compare that fails: named in the ledger, then failed. */
+    const cfail = (at, kind, why) => { L.note(at, kind, why); return stop('failed', 'failed', why); };
+    const pr = probeLinks(t.tmp);
+    if (pr) { if (pr.left) { left.push(pr.left); leftWhy.push(pr.why); } return pr.refused ? stop('refused', 'no-links', pr.why) : stop('failed', 'link-check', pr.why); }
+    /* C: the final compare. */
+    { const p = hook('beforeCompare', target); if (thenable(p)) await p; }
+    let l1;
+    try { l1 = typeListing(where); } catch (e) { return cfail('step-types', 'unreadable', 'step-types/ couldn\'t be listed (' + errText(e) + ')'); }
+    let copies = S.copiesOf(name, l1.names);
+    if (copies.length) return stop('refused', 'copies', '', { copies: copies.map((c) => 'step-types/' + c) });
+    let snap = null;
+    let st0;
+    try { st0 = lstatBig(target); } catch (e) { return cfail(rel, 'unreadable', rel + ' couldn\'t be checked (' + errText(e) + ')'); }
+    if (seenBytes === null) { if (st0) return stop('refused', 'changed', ''); }
+    else {
+      if (!st0) return stop('refused', 'changed', '');
+      if (st0.isSymbolicLink() || !st0.isFile()) return cfail(rel, 'link', rel + ' is a folder or a link now; Flightdeck never saves through one.');
+      const r = readThrough(target, 'C', seenBytes.length + 1, st0, null);
+      if (r.fail === 'gone' || r.fail === 'moved') return stop('refused', 'changed', '');
+      if (r.fail) return cfail(rel, r.fail === 'link' || r.fail === 'notfile' ? 'link' : 'unreadable', r.fail === 'close' ? r.why : rel + ' couldn\'t be compared (' + r.why + ')');
+      if (r.filled || !r.bytes.equals(seenBytes) || !sameMeta(r.first, r.snap)) return stop('refused', 'changed', '');
+      snap = r.snap;
+      hook('afterSnapshot', target, 'C');
+    }
+    let l2;
+    try { l2 = typeListing(where); } catch (e) { return cfail('step-types', 'unreadable', 'step-types/ couldn\'t be listed (' + errText(e) + ')'); }
+    copies = S.copiesOf(name, l2.names);
+    if (copies.length) return stop('refused', 'copies', '', { copies: copies.map((c) => 'step-types/' + c) });
+    { const p = hook('afterFinalListing', target); if (thenable(p)) await p; }
+    let fin;
+    try { fin = lstatBig(target); } catch (e) { return cfail(rel, 'unreadable', rel + ' couldn\'t be checked (' + errText(e) + ')'); }
+    if (seenBytes === null) { if (fin) return stop('refused', 'changed', ''); }
+    else {
+      if (!fin) return stop('refused', 'changed', '');
+      if (fin.isSymbolicLink() || !fin.isFile()) return cfail(rel, 'link', rel + ' is a folder or a link now; Flightdeck never saves through one.');
+      if (!sameMeta(fin, snap)) return stop('refused', 'changed', '');
+    }
+    { const p = hook('afterCompare', target); if (thenable(p)) await p; }
+    /* W: the commit. Only the link or the rename returning says this command wrote. */
+    let commit = 'yes', commitWhy = null;
+    if (seenBytes === null) {
+      try { fs.linkSync(t.tmp, target); } catch (e) { if (e.code === 'EEXIST') return stop('refused', 'changed', ''); commit = 'unknown'; commitWhy = errText(e); }
+      if (commit === 'yes') try { hook('afterLink', target); } catch (e) { /* a test hook; the commit stands */ }
+    } else {
+      try { fs.renameSync(t.tmp, target); } catch (e) { commit = 'unknown'; commitWhy = errText(e); }
+    }
+    if (commit === 'yes') { try { const p = hook('afterCommit', target); if (thenable(p)) await p; } catch (e) { /* a test hook; the commit stands */ } }
+    /* U: the temporary file after a link (a rename moved it; an uncertain rename may have left it). */
+    if (seenBytes === null || commit === 'unknown') { const w = removeOurs(t.tmp, t.ours, commit === 'yes'); if (w) { left.push(t.tmp); leftWhy.push(w); } }
+    /* B: read back, for information only when the commit is unknown. */
+    const b = readBack(target, t.ours, data);
+    /* What the read-back couldn't read, of this save or of what replaced it, is named; the outcome stays what it is. */
+    if (b.kind) L.note(rel, b.kind, b.why || 'it couldn\'t be read back');
+    out.rev.now = b.back === 'same' || b.back === 'other' ? b.now : null;
+    if (commit === 'unknown') return finish({ commit: 'unknown', back: b.back, why: commitWhy });
+    loadIf(l2.files, 'C');
+    /* H: the history line, created once. */
+    const h = createOnce(dir, historyPath.split('/'), Buffer.from(JSON.stringify(line) + '\n', 'utf8'));
+    h.left.forEach((p, i) => { left.push(p); leftWhy.push(h.leftWhy[i]); });
+    return finish({ commit: 'yes', back: b.back, why: b.why || '', history: { commit: h.commit, why: h.why }, historyPath });
+  } catch (e) {
+    return refuse('failed', 'failed', e instanceof Refused ? e.message : 'The team folder couldn\'t be changed: ' + errText(e));
+  }
+}
+async function typeMain(argv) {
+  const VAL = ['--expect', '--from', '--asked-by', '--note'], val = {};
+  const args = argv.filter((a, i) => !a.startsWith('--') && !(i > 0 && VAL.indexOf(argv[i - 1]) >= 0));
+  argv.forEach((a, i) => { if (VAL.indexOf(a) >= 0 && i + 1 < argv.length && !(argv[i + 1].startsWith('--') && argv[i + 1] !== '-')) val[a] = argv[i + 1]; });
+  let eng;
+  const sub = args[1];
+  try { eng = loadEngine(); if (_hooks.engine) _hooks.engine(eng); } catch (e) {
+    /* type save answers in its own contract even without an engine: failed, nothing changed. */
+    if (sub === 'save') return { out: JSON.stringify(writeShell('', null, 'failed', { kind: 'failed', why: errText(e) }, 'Nothing was changed. Flightdeck couldn\'t load: ' + bare(errText(e)) + '.'), null, 2), code: EXIT.error };
+    return { out: JSON.stringify({ contract: 'flightdeck-read/2', app: '', error: { kind: 'failed', why: e.message }, problems: [] }, null, 2), code: EXIT.error };
+  }
+  if (sub === 'list' || sub === 'read') return typeRead(eng, argv, args);
+  if (sub === 'save') return typeSave(eng, argv, args, val);
+  return typeFail(eng, 'usage', 'say list, read or save, for example: flightdeck type read <team folder> <id> --json');
+}
+
 const HELP = `flightdeck: team process checklists, in one HTML file
 
   flightdeck open                     open the app in this package: the first time, the welcome (start your team, join
@@ -1735,9 +2458,19 @@ const HELP = `flightdeck: team process checklists, in one HTML file
                                       read; otherwise write a proposal a person applies in Flightdeck
   flightdeck draft propose <same as save>
                                       always write a proposal
+  flightdeck draft check <team folder> <process> [--from <file|->] --json
+                                      the verdict Review & publish gives the draft (or the text in the file): what
+                                      stops publishing and the tips, from the folder as it is now. Only reads
   flightdeck skill register <team folder> --from <file|-> [--json]
                                       for AI assistants: register a skill against the exact version it was built
                                       from (Flightdeck 2.0). The only writer of skill-registrations/
+  flightdeck type list <team folder> --json
+                                      for AI assistants: the team's step types, in the order Flightdeck reads them
+  flightdeck type read <team folder> <id> --json
+                                      one step type: its state, its exact text and rev (none when it isn't there)
+  flightdeck type save <team folder> <id> --expect <rev|none> --from <file|-> [--asked-by <person id>]
+                    [--note "<text>"] [--dry-run] --json
+                                      add or change a step type, only when it's exactly what you read
   flightdeck path                     print where the app file is
   flightdeck version                  print this version
 
@@ -1759,6 +2492,12 @@ or version.
 flightdeck draft changes the team folder (contract flightdeck-draft/1). Exit code 0: written or proposed (read: complete);
 4: read, partial; 1: usage, missing-base, too-big or failed; 5: read, no such process.
 
+flightdeck type save changes the team folder (contract flightdeck-write/1): it writes step-types/<id>.json and one
+history line, never anything else. It compares the exact bytes type read gave and reads its save back. Like two Flightdeck
+windows in different browsers, two saves at the same instant can replace one another without either being told. Exit
+code 0: done, same or checked; 4: held, partial, replaced, unverified or unsure (read the type again); 1: refused or
+failed (nothing was changed).
+
 export never changes the team folder and never writes a pack into it. It prints the pack's SHA-256: keep it somewhere
 separate. Exit code 0: a complete pack; 4: a partial pack (made, with what changed or is missing listed); 1: no pack.
 
@@ -1776,6 +2515,7 @@ function main(argv) {
   if (first === 'plan' && !argv.includes('--help')) return requestMain(argv);
   if (first === 'skill' && !argv.includes('--help')) return skillMain(argv);
   if (first === 'report' && !argv.includes('--help')) return reportMain(argv);
+  if (first === 'type' && !argv.includes('--help')) return typeMain(argv);
   const ti = argv.indexOf('--to'), to = ti >= 0 ? argv[ti + 1] : null;
   if (ti >= 0 && (!to || to.startsWith('--'))) fail('say which folder after --to, for example: flightdeck skills --to ~/skills');
   /* Flags that take a value: the value is never read as a command or a folder. */