@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/context/delivery-store.js

@@ -0,0 +1,100 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const { boundedAcquire, updateTaskState } = require('../task-state.js');
+const { taskRecord } = require('../task-scope.js');
+
+const MAX_DELIVERIES = 5;
+const ACTUAL_UNMEASURED = 'no harness reports token usage to an external CLI; profile tokenTelemetry unverified';
+
+function assertValidDeliveryEntry(entry     )       {
+  if (!entry || typeof entry !== 'object') throw new Error('Delivery entry must be an object');
+  if (!entry.tokens || !entry.tokens.estimated) throw new Error('Delivery entry requires tokens.estimated');
+  if (typeof entry.tokens.estimated.value !== 'number' || entry.tokens.estimated.basis !== 'estimated:bytes/4') {
+    throw new Error('Delivery entry tokens.estimated must use estimated:bytes/4');
+  }
+  if (entry.tokens.actual?.basis?.startsWith('estimated:')) {
+    throw new Error('Delivery entry tokens.actual cannot use an estimated basis');
+  }
+  for (const expansion of entry.expansions || []) {
+    if (typeof expansion.reason !== 'string' || expansion.reason.trim() === '') {
+      throw new Error('Delivery expansion reason must not be empty');
+    }
+  }
+}
+
+function makeTokenRecord(bytes        )      {
+  return {
+    estimated: { value: Math.ceil(bytes / 4), basis: 'estimated:bytes/4' },
+    actual: { unmeasured: ACTUAL_UNMEASURED },
+  };
+}
+
+function createDeliveryEntry({ pack, form, harness = null, sources = {}, expansions = [], retention = null }     )      {
+  const items = pack.deliveryAllItems || pack.deliveryItems || [];
+  const digests = Object.fromEntries(items.map((item     ) => [item.id, item.digest]));
+  const mandatoryIds = items.filter((item     ) => item.cls === 'mandatory').map((item     ) => item.id);
+  const harnessId = harness || 'unstated';
+  const bytes = Number(pack.size?.totalBytes || 0);
+  const entry = {
+    key: `${pack.delivery.packDigest}.${form}.${harnessId}`,
+    packDigest: pack.delivery.packDigest,
+    form,
+    harness,
+    firstAt: new Date().toISOString(),
+    mode: pack.mode || 'full',
+    budget: { maxBytes: pack.budget.maxBytes, source: pack.budget.source },
+    since: pack.delivery.since || null,
+    deltaRefused: pack.delivery.deltaRefused || null,
+    retention: retention || { status: 'unknown', basis: 'contextProfile.retention is unverified' },
+    items: digests,
+    mandatoryIds,
+    sources,
+    pointers: pack.pointers || [],
+    bytes,
+    tokens: makeTokenRecord(bytes),
+    omissions: (pack.deliveryOmissions || []).map((item     ) => ({ ...item })),
+    expansions: [...expansions],
+  };
+  assertValidDeliveryEntry(entry);
+  return entry;
+}
+
+function readDeliveryEntry({ projectRoot, taskId, slug = null, packDigest, fsImpl = fs }     )             {
+  const file = taskRecord({ projectRoot, store: 'delivery', taskId, slug, fsImpl }).read;
+  try {
+    const disk = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+    return (Array.isArray(disk.deliveries) ? disk.deliveries : []).find((entry     ) => entry.packDigest === packDigest) || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Persist a delivery under the same bounded lock used by task state. */
+function recordDelivery({ projectRoot, taskId, slug = null, entry, fsImpl = fs, acquire = boundedAcquire, supersedesKey = null }     )      {
+  assertValidDeliveryEntry(entry);
+  if (typeof taskId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(taskId) || taskId.includes('..')) {
+    throw new Error(`Invalid task id '${taskId}'`);
+  }
+  const { file, seed } = taskRecord({ projectRoot, store: 'delivery', taskId, slug, fsImpl });
+  const written = updateTaskState({
+    fsImpl,
+    file,
+    prepare: seed,
+    acquire: (impl     , target        ) => acquire(impl, target, { retries: 3, waitMs: 5 }),
+    build(disk     ) {
+      const deliveries = Array.isArray(disk?.deliveries) ? disk.deliveries : [];
+      if (deliveries.some((existing     ) => existing.key === entry.key)) {
+        return null;
+      }
+      const current = supersedesKey ? deliveries.filter((existing     ) => existing.key !== supersedesKey) : deliveries;
+      return { taskId, deliveries: [...current, entry].slice(-MAX_DELIVERIES) };
+    },
+  });
+  if (written === null) return null;
+  return { key: entry.key, recorded: true, reason: null };
+}
+
+module.exports = { ACTUAL_UNMEASURED, assertValidDeliveryEntry, createDeliveryEntry, makeTokenRecord, readDeliveryEntry, recordDelivery };

package/src/runtime/context/emission-rules.js

@@ -0,0 +1,118 @@
+'use strict';
+
+// Rule compiler for the hook emission table (078 IC-003, DEC-005). Run directly by Node native
+// type-stripping:
+//
+//   node src/runtime/context/emission-rules.js --write   rewrite the committed table
+//   node src/runtime/context/emission-rules.js --check   exit 0 equal, 1 differs, 2 usage
+//
+// The table is compiled from EMISSION_RULES, never written by hand: each rule's finite domain is
+// enumerated through INPUT_DOMAINS and ruleAction(), so every arm the hook reads is the action
+// arbitrate() gives that vector. Every combination is written as its own literal arm; a pattern
+// holds no glob, so the hook's lookup matches exactly what IC-002 lists and nothing else.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { EMISSION_RULES, INPUT_DOMAINS, ruleAction } = require('./arbitrate.js');
+
+const TABLE_REL = 'core/harnesses/shared/hooks/policies/emission-rules.sh';
+const RULES_VERSION = 1;
+const MAX_BYTES_DEFAULT = 16384;
+const SUMMARY_CAP = 4000;
+const SUMMARY_READ = 65536;
+
+/** Every value combination of the named inputs, in vector order. */
+function combinations(inputs                   )             {
+  let out             = [[]];
+  for (const name of inputs) {
+    const domain                    = INPUT_DOMAINS[name];
+    out = out.flatMap((prefix) => domain.map((value) => [...prefix, value]));
+  }
+  return out;
+}
+
+/** JSON with object keys sorted at every depth, so the digest does not depend on key order. */
+function canonicalJson(value         )         {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const entries = Object.keys(value          ).sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson((value                           )[key])}`);
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function rulesDigest(rules                    )         {
+  return crypto.createHash('sha256').update(canonicalJson(rules), 'utf8').digest('hex');
+}
+
+function compare(a        , b        )         {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+                                                                                        
+
+/** Every non-skip combination of every rule, sorted by event, segment, vector. */
+function compileArms(rules                 = EMISSION_RULES)                {
+  const arms                = [];
+  for (const r of rules) {
+    for (const values of combinations(r.inputs)) {
+      const action = ruleAction(r, values);
+      if (action !== 'skip') arms.push({ event: r.event, segment: r.segment, vector: values.join(':'), action });
+    }
+  }
+  return arms.sort((a, b) => compare(a.event, b.event) || compare(a.segment, b.segment) || compare(a.vector, b.vector));
+}
+
+/** A value safe inside a single-quoted bash pattern, with no glob character. */
+function literal(text        )         {
+  if (!/^[A-Za-z0-9._:|-]+$/.test(text)) throw new TypeError(`emission-rules: ${JSON.stringify(text)} is not a plain token`);
+  return text;
+}
+
+/** IC-003: the full text of `emission-rules.sh`. */
+function compileEmissionTable(rules                 = EMISSION_RULES)         {
+  const lines = [
+    '# Generated by node src/runtime/context/emission-rules.js --write. Do not edit.',
+    `# rules-digest: sha256:${rulesDigest(rules)}`,
+    `DF_RULES_VERSION=${RULES_VERSION}`,
+    `DF_RULES_MAX_BYTES_DEFAULT=${MAX_BYTES_DEFAULT}`,
+    `DF_RULES_SUMMARY_CAP=${SUMMARY_CAP}`,
+    `DF_RULES_SUMMARY_READ=${SUMMARY_READ}`,
+    'doflow_emission_rule() {',
+    "  # $1 = event.segment, $2 = vector: input values joined with ':' in IC-002 order",
+    '  case "$1|$2" in',
+  ];
+  for (const arm of compileArms(rules)) {
+    lines.push(`    '${literal(`${arm.event}.${arm.segment}|${arm.vector}`)}') DF_ACTION=${literal(arm.action)} ;;`);
+  }
+  lines.push('    *) DF_ACTION=skip ;;', '  esac', '}');
+  return `${lines.join('\n')}\n`;
+}
+
+const USAGE = 'usage: node src/runtime/context/emission-rules.js --write|--check\n';
+
+/** The CLI: 0 written or equal, 1 the committed table differs from the rules, 2 usage. */
+function main(argv          )         {
+  if (argv.length !== 1 || (argv[0] !== '--write' && argv[0] !== '--check')) {
+    process.stderr.write(USAGE);
+    return 2;
+  }
+  const target = path.join(REPO_ROOT, TABLE_REL);
+  const expected = compileEmissionTable();
+  if (argv[0] === '--write') {
+    fs.writeFileSync(target, expected);
+    return 0;
+  }
+  let actual               ;
+  try { actual = fs.readFileSync(target, 'utf8'); } catch { actual = null; }
+  if (actual === expected) return 0;
+  process.stderr.write(`emission-rules: ${TABLE_REL} is ${actual === null ? 'missing' : 'stale'}; run node src/runtime/context/emission-rules.js --write\n`);
+  return 1;
+}
+
+module.exports = { TABLE_REL, canonicalJson, compileArms, compileEmissionTable, rulesDigest };
+
+if (require.main === module) process.exitCode = main(process.argv.slice(2));

package/src/runtime/context/identity.js

@@ -0,0 +1,227 @@
+'use strict';
+
+// Session identity reader (078 IC-007). Run directly by Node native type-stripping.
+//
+// The TypeScript twin of `policies/identity.sh`: both read the launcher-set environment the same
+// way, and test/fixtures/identity/cases.json is the corpus both must agree on (G38.6). Identity
+// comes only from DOFLOW_RUN_ID, DOFLOW_ATTEMPT, DOFLOW_LINEAGE_ID, DOFLOW_SESSION_ROLE and
+// DOFLOW_WORKTREE plus the payload's session_id and cwd; it is never inferred from git or from the
+// harness's own idea of a main session.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { configHome } = require('../config-home.js');
+
+/** DEC-024: a launched unit id `L.<run>.<lineage>.<attempt>` stays inside the 128-character session-dirs match. */
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,55}$/;
+const ATTEMPT_PATTERN = /^[1-9][0-9]{0,3}$/;
+const DEFAULT_RUN = 'local';
+const UNKNOWN_ROLE_LINE = '[doflow] unknown DOFLOW_SESSION_ROLE; treating session as worker\n';
+
+                                              
+                              
+                                                        
+                                                                             
+
+                           
+              
+                  
+                  
+             
+                   
+                           
+                 
+                  
+                            
+ 
+
+                          
+              
+                    
+                 
+                                
+ 
+
+let roleWarned = false;
+
+/** `<config home>/doflow/session-env`, the root `policies/lib.sh` names STATE_DIR; null with no config home (IC-010), and the callers then skip session state. */
+function stateDir(env      = process.env)                {
+  const { dir } = configHome(env);
+  return dir === null ? null : path.join(dir, 'session-env');
+}
+
+/** `(cd "$p" && pwd -P)`: the physical path of an existing directory, or null. */
+function physicalDir(p        )                {
+  try {
+    if (!fs.statSync(p).isDirectory()) return null;
+    return fs.realpathSync.native(p);
+  } catch {
+    return null;
+  }
+}
+
+/** `canonicalize_path` from policies/lib.sh: resolve the parent chain of an existing path, never its leaf. */
+function canonicalizePath(p        )         {
+  try {
+    fs.statSync(p); // `[[ -e ]]` follows symlinks, so a dangling link is "missing"
+    const dir = fs.realpathSync.native(path.dirname(p));
+    const base = path.basename(p);
+    return dir === '/' ? `/${base}` : `${dir}/${base}`;
+  } catch {
+    return p;
+  }
+}
+
+/** `cwd_hash` from policies/lib.sh: first 16 hex chars of sha256 over the canonical path plus `echo`'s newline. */
+function cwdHash(p        )         {
+  let canonical = physicalDir(p) ?? canonicalizePath(p);
+  // bash hashes `pwd -P`, which Git Bash prints as /c/Users/x; hash the same spelling for a native C:\\Users\\x.
+  if (process.platform === 'win32') {
+    const drive = /^([A-Za-z]):[\\/]?(.*)$/.exec(canonical);
+    if (drive) canonical = `/${drive[1].toLowerCase()}${drive[2] ? `/${drive[2].replace(/\\/g, '/')}` : ''}`;
+  }
+  return crypto.createHash('sha256').update(`${canonical}\n`).digest('hex').slice(0, 16);
+}
+
+/** `tr '[:upper:]' '[:lower:]'` on the role, ASCII only, then today's mapping: unset is main, unknown is worker. */
+function readRole(raw                    )                                   {
+  const role = (raw || '').replace(/[A-Z]/g, (c) => c.toLowerCase());
+  if (role === '' || role === 'main') return { role: 'main', unknown: false };
+  if (role === 'worker') return { role: 'worker', unknown: false };
+  return { role: 'worker', unknown: true };
+}
+
+/** DOFLOW_WORKTREE canonicalised when it names an absolute existing directory; else the payload cwd as given (cwdHash canonicalises for the store key). */
+function readWorktree(raw                    , cwd        )         {
+  if (raw && raw.startsWith('/')) {
+    const dir = physicalDir(raw);
+    if (dir !== null) return dir;
+  }
+  return cwd;
+}
+
+/**
+ * Create `sessions/<unitId>/bound` exclusively, holding the session id. True when this session owns
+ * the unit (just bound, or bound earlier by the same session); false when another session bound it,
+ * and false when it cannot be decided (the store is unwritable, `bound` is a symlink, which is never
+ * followed, or `bound` is still empty after one retry). Never throws: the caller treats false as an
+ * inherited session (L1-04).
+ */
+function bindUnit(env     , unitId        , sessionId        )          {
+  const root = stateDir(env);
+  if (root === null) return false;
+  const dir = path.join(root, 'sessions', unitId);
+  const file = path.join(dir, 'bound');
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const fd = fs.openSync(file, 'wx');
+    try {
+      fs.writeSync(fd, `${sessionId}\n`);
+    } finally {
+      fs.closeSync(fd);
+    }
+    return true;
+  } catch (error     ) {
+    if (error?.code !== 'EEXIST') return false;
+  }
+  // `IFS= read -r bound` of a regular file, not a symlink: its first line. An empty first line may
+  // be a concurrent binder between its create and its write, so it is read once more.
+  for (let tries = 0; tries < 2; tries++) {
+    let bound        ;
+    try {
+      if (!fs.lstatSync(file).isFile()) return false;
+      bound = fs.readFileSync(file, 'utf8').split('\n')[0];
+    } catch {
+      return false;
+    }
+    if (bound !== '') return bound === sessionId;
+  }
+  return false;
+}
+
+/** IC-007: the session identity from the environment and the payload's session id and cwd. */
+function resolveIdentity(env     , options                )                  {
+  const { cwd, sessionId, bind = false } = options;
+  const diagnostics = new Set            ();
+
+  const { role, unknown } = readRole(env.DOFLOW_SESSION_ROLE);
+  if (unknown) {
+    diagnostics.add('role-unknown');
+    if (!roleWarned) {
+      roleWarned = true;
+      (options.warn ?? ((line        ) => process.stderr.write(line)))(UNKNOWN_ROLE_LINE);
+    }
+  }
+
+  const rawRun = env.DOFLOW_RUN_ID || '';
+  const runValid = rawRun !== '' && rawRun !== DEFAULT_RUN && ID_PATTERN.test(rawRun);
+  if (rawRun !== '' && !runValid) diagnostics.add('identity-invalid');
+  const run = runValid ? rawRun : DEFAULT_RUN;
+
+  const rawAttempt = env.DOFLOW_ATTEMPT || '';
+  const attempt = ATTEMPT_PATTERN.test(rawAttempt) ? rawAttempt : '';
+
+  const rawLineage = env.DOFLOW_LINEAGE_ID || '';
+  const lineageValid = rawLineage !== '' && ID_PATTERN.test(rawLineage);
+  if (rawLineage !== '' && !lineageValid) diagnostics.add('identity-invalid');
+  let lineage        ;
+  if (rawRun !== '' && !runValid) lineage = 'solo';
+  else if (rawLineage === '') lineage = role === 'main' ? 'main' : 'solo';
+  else lineage = lineageValid ? rawLineage : 'solo';
+
+  let lineageKind              = 'solo';
+  if (runValid && lineageValid && attempt !== '') lineageKind = 'launched';
+  else if (run === DEFAULT_RUN && lineage === 'main') lineageKind = 'default-main';
+
+  let unitId = lineageKind === 'launched' ? `L.${run}.${lineage}.${attempt}` : sessionId;
+  if (lineageKind === 'launched' && bind) {
+    // An empty session id cannot bind: solo with an empty unit and no capture, as identity.sh.
+    // Any other failure to bind is an inherited session (DEC-044).
+    const mine = sessionId !== '' && bindUnit(env, unitId, sessionId);
+    if (!mine) {
+      if (sessionId !== '') diagnostics.add('identity-inherited');
+      lineageKind = 'solo';
+      lineage = 'solo';
+      unitId = sessionId;
+    }
+  }
+
+  return {
+    run,
+    attempt,
+    lineage,
+    role,
+    worktree: readWorktree(env.DOFLOW_WORKTREE, cwd),
+    lineageKind,
+    unitId,
+    session: sessionId,
+    diagnostics: [...diagnostics].sort(),
+  };
+}
+
+/**
+ * The run ledger's identity fields (082 IC-034, DEC-042). Each value is tested on its own and
+ * omitted, never written, when absent or invalid: `run` by `resolveIdentity`'s `runValid` rule
+ * (non-empty, not `local`, `ID_PATTERN`), `lineage` by `ID_PATTERN`, `attempt` by `ATTEMPT_PATTERN`.
+ */
+function identityFields(env     )                                                       {
+  const out                                                       = {};
+  const run = env.DOFLOW_RUN_ID || '';
+  if (run !== '' && run !== DEFAULT_RUN && ID_PATTERN.test(run)) out.run = run;
+  const lineage = env.DOFLOW_LINEAGE_ID || '';
+  if (ID_PATTERN.test(lineage)) out.lineage = lineage;
+  const attempt = env.DOFLOW_ATTEMPT || '';
+  if (ATTEMPT_PATTERN.test(attempt)) out.attempt = attempt;
+  return out;
+}
+
+module.exports = {
+  ATTEMPT_PATTERN,
+  ID_PATTERN,
+  UNKNOWN_ROLE_LINE,
+  cwdHash,
+  identityFields,
+  resolveIdentity,
+  stateDir,
+};