@sun-asterisk/sungen 3.2.35 → 3.3.0-alpha.10

package/src/decisions/viewpoint-baseline-adapter.ts

@@ -0,0 +1,74 @@
+/**
+ * The accepted viewpoint baseline, seen as decisions — read-only (DOS-11.4; storage moves in P1).
+ *
+ * `sungen audit --accept-viewpoint` records `.sungen/viewpoint-baseline.json` (harness/viewpoint-
+ * baseline.ts). Each unit in it is projected as one `viewpoint-acceptance` decision, without moving or
+ * rewriting anything: no file is written here, ever.
+ *
+ * The file is agent-writable, so a unit is projected only while its record equals the one committed
+ * in git HEAD (review H1) — otherwise it would turn a local edit into a hash-valid decision. Anything
+ * not projected is reported: an `untrusted` unit, an `invalid` unit record, an `unreadable` file.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { canonicalJson, sealDecision } from './decision-identity';
+import { DecisionProblem, PROJECT_SCOPE } from './decision-file';
+import { committedJson } from './git-head-trust';
+import { ReadDecision } from './read-decisions';
+
+/** Same location harness/viewpoint-baseline.ts writes. */
+const baselineFile = (projectRoot: string): string => path.join(projectRoot, '.sungen', 'viewpoint-baseline.json');
+const EPOCH = '1970-01-01T00:00:00.000Z';
+
+interface UnitRecord { hash: string; ids: string[]; recordedAt?: string; fileHash?: string }
+
+function isUnitRecord(v: unknown): v is UnitRecord {
+  const r = v as UnitRecord;
+  return !!r && typeof r === 'object' && typeof r.hash === 'string' && Array.isArray(r.ids) && r.ids.every((i) => typeof i === 'string');
+}
+const unitsOf = (raw: unknown): Record<string, unknown> | null => {
+  const u = (raw as { units?: unknown } | null)?.units;
+  return u && typeof u === 'object' && !Array.isArray(u) ? u as Record<string, unknown> : null;
+};
+
+function project(unit: string, r: UnitRecord, file: string): ReadDecision {
+  const at = typeof r.recordedAt === 'string' && !Number.isNaN(Date.parse(r.recordedAt)) ? new Date(r.recordedAt).toISOString() : EPOCH;
+  const entry = sealDecision({
+    kind: 'viewpoint-acceptance',
+    anchors: [],
+    text: `Accept the test-viewpoint declaration of ${unit} as the baseline`,
+    reason: 'Accepted with sungen audit --accept-viewpoint (legacy .sungen/viewpoint-baseline.json)',
+    payload: { unit, hash: r.hash, ids: r.ids, ...(typeof r.fileHash === 'string' ? { fileHash: r.fileHash } : {}) },
+    source: { by: 'unknown', where: 'legacy:viewpoint-baseline' },
+    valid_from: at,
+    visibility: 'internal',
+  }, PROJECT_SCOPE);
+  return { ...entry, scope: PROJECT_SCOPE, path: file };
+}
+
+export function viewpointAcceptanceDecisions(projectRoot: string): { entries: ReadDecision[]; problems: DecisionProblem[] } {
+  const file = baselineFile(projectRoot);
+  const entries: ReadDecision[] = [];
+  const problems: DecisionProblem[] = [];
+  if (!fs.existsSync(file)) return { entries, problems };
+  let units: Record<string, unknown> | null;
+  try {
+    units = unitsOf(JSON.parse(fs.readFileSync(file, 'utf8')));
+  } catch (err) {
+    problems.push({ path: file, code: 'unreadable', message: `viewpoint baseline cannot be read: ${err instanceof Error ? err.message : String(err)}` });
+    return { entries, problems };
+  }
+  if (!units) return { entries, problems: [{ path: file, code: 'unreadable', message: 'viewpoint baseline has no `units` mapping' }] };
+
+  const committed = unitsOf(committedJson(projectRoot, file)) ?? {};
+  for (const unit of Object.keys(units).sort()) {
+    const r = units[unit];
+    if (!isUnitRecord(r)) { problems.push({ path: file, code: 'invalid', message: `viewpoint baseline record for ${unit} is malformed; not projected` }); continue; }
+    if (!(unit in committed) || canonicalJson(committed[unit]) !== canonicalJson(r)) {
+      problems.push({ path: file, code: 'untrusted', message: `viewpoint baseline for ${unit} is not the one in git HEAD — not taken as a decision (decision.in-run); commit it through review` });
+      continue;
+    }
+    entries.push(project(unit, r, file));
+  }
+  return { entries, problems };
+}

package/src/decisions/waiver-decisions.ts

@@ -0,0 +1,56 @@
+/**
+ * Journey waivers as decisions (DOS-13.5).
+ *
+ * A waiver entry is `kind: waiver`, `payload.obligation`, `evidence_hash` = the audit hash the waiver
+ * was given against (legacy `auditHashAtWaive`). Per obligation the waiver in force is the latest
+ * (by `valid_from`) entry that nothing supersedes. Whether it COUNTS is the old rule, unchanged: only
+ * while `evidence_hash` equals the current audit hash; otherwise it is STALE and goes back to a human.
+ */
+import { DecisionDraft, DecisionEntry, DecisionSource } from './decision-schema';
+import { ReadDecision } from './read-decisions';
+
+/** The legacy shape in `.sungen/journey/<slug>.state.json` — still dual-written for one release. */
+export interface LegacyWaiver { reason: string; at: string; auditHashAtWaive: string }
+
+const norm = (s: string): string => s.normalize('NFC').replace(/\r\n?/g, '\n').trim();
+
+export function isLegacyWaiver(w: unknown): w is LegacyWaiver {
+  const x = w as LegacyWaiver;
+  return !!x && typeof x === 'object' && typeof x.reason === 'string' && norm(x.reason).length > 0
+    && typeof x.at === 'string' && !Number.isNaN(Date.parse(x.at)) && typeof x.auditHashAtWaive === 'string';
+}
+
+/** Same decision: same reason against the same evidence (the time it was recorded does not matter). */
+export function sameWaiver(a: LegacyWaiver, b: LegacyWaiver): boolean {
+  return norm(a.reason) === norm(b.reason) && a.auditHashAtWaive === b.auditHashAtWaive;
+}
+
+export function waiverDraft(obligation: string, w: LegacyWaiver, source: DecisionSource, supersedes?: string): DecisionDraft {
+  return {
+    kind: 'waiver',
+    anchors: [],
+    text: `Waive ${obligation}`,
+    reason: w.reason,
+    payload: { obligation },
+    source,
+    valid_from: w.at,
+    ...(supersedes ? { supersedes } : {}),
+    visibility: 'internal',
+    evidence_hash: w.auditHashAtWaive,
+  };
+}
+
+export function asLegacyWaiver(e: DecisionEntry): LegacyWaiver {
+  return { reason: e.reason, at: e.valid_from, auditHashAtWaive: e.evidence_hash ?? '' };
+}
+
+/** obligation → the waiver entry in force. `entries` come from readDecisions (sorted by time). */
+export function effectiveWaiverEntries(entries: ReadDecision[]): Map<string, ReadDecision> {
+  const out = new Map<string, ReadDecision>();
+  for (const e of entries) {
+    const ob = e.payload?.obligation;
+    if (e.kind !== 'waiver' || e.superseded_by || typeof ob !== 'string') continue;
+    out.set(ob, e);   // ascending time: the latest wins
+  }
+  return out;
+}

package/src/exporters/csv-exporter.ts

@@ -439,12 +439,12 @@ export function renderCsv(summary: ScreenSummary, rows: TestCaseRow[], specLink:
  * multi-locale delivery aggregator. Pass an empty string to force the
  * base (no suffix) variant.
  */
-export function writeCsv(cwd: string, screen: string, csvContent: string, locale?: string | null): string {
+export function writeCsv(cwd: string, screen: string, csvContent: string, locale?: string | null, opts: DeliverableFileOptions = {}): string {
   const outDir = path.join(cwd, 'qa', 'deliverables');
   if (!fs.existsSync(outDir)) {
     fs.mkdirSync(outDir, { recursive: true });
   }
-  const outPath = path.join(outDir, `${deliverableBasename(screen, locale)}.csv`);
+  const outPath = path.join(outDir, `${deliverableBasename(screen, locale, opts)}.csv`);
   fs.writeFileSync(outPath, csvContent, 'utf-8');
   return outPath;
 }
@@ -455,8 +455,16 @@ export function writeCsv(cwd: string, screen: string, csvContent: string, locale
  * locale is given (or `SUNGEN_ENV` is set and no explicit override). Pass
  * `null` / empty string to force the base variant.
  */
-export function deliverableBasename(screen: string, locale?: string | null): string {
+export function deliverableBasename(screen: string, locale?: string | null, opts: DeliverableFileOptions = {}): string {
   const effective = locale !== undefined ? locale : process.env.SUNGEN_ENV;
-  return effective ? `${screen}-testcases.${effective}` : `${screen}-testcases`;
+  return `${effective ? `${screen}-testcases.${effective}` : `${screen}-testcases`}${opts.draft ? DRAFT_MARK : ''}`;
 }
 
+/**
+ * A DRAFT render (a watermarked `--preview`) is written beside the official deliverable, never onto it
+ * (#965): `<screen>-testcases[.env].DRAFT.<ext>`. Readers of `qa/deliverables/` skip it (isDraftDeliverable).
+ */
+export interface DeliverableFileOptions { draft?: boolean }
+export const DRAFT_MARK = '.DRAFT';
+export const isDraftDeliverable = (fileName: string): boolean => /\.DRAFT\.[^.]+$/.test(fileName);
+

package/src/exporters/matrix/build.ts

@@ -34,6 +34,7 @@ import {
   MAX_VARIANTS_PER_ITEM,
 } from './types';
 import { runGates } from './gates';
+import { CATALOG_GATE_RULES, GateRules } from '../../harness/gates/resolve-rule';
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 
@@ -128,6 +129,8 @@ export interface BuildInputs {
   specText?: string;
   /** apis.yaml endpoint catalog (api units) — renders `@api:` calls as request blocks. */
   apiCatalog?: Record<string, ApiCatalogEntry>;
+  /** The unit's gate rules (catalog + gate-overrides, OES-11.2); the catalog alone when absent. */
+  gateRules?: GateRules;
 }
 
 /**
@@ -594,7 +597,7 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
     variantsByVp.set(v.vpId, list);
   }
 
-  const findings = runGates({ inputs, variants, variantsByVp });
+  const findings = runGates({ inputs, variants, variantsByVp, rules: inputs.gateRules });
   const stale = new Set(findings.filter((f) => f.gate === 'E' && f.ref).map((f) => f.ref as string));
 
   const items: DeliveryItem[] = map.groups.map((g) => {
@@ -660,22 +663,21 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
   // requirements/spec.md; @spec: traces mark `covered`; the map's `requirements:`
   // section carries the reviewed overrides (partially_covered / not_applicable / …).
   const requirements = computeRequirements(inputs.specText ?? '', map, items);
+  // Gate R levels come from the catalog like every other matrix gate (OES-11.2); `off` drops the finding.
+  const gateR = (rule: string, message: string): void => {
+    const { severity } = (inputs.gateRules ?? CATALOG_GATE_RULES).resolve(rule);
+    if (severity !== 'off') findings.push({ gate: 'R', severity, message });
+  };
   const gaps = requirements.filter((r) => r.status === 'gap');
   if (gaps.length > 0) {
-    findings.push({
-      gate: 'R', severity: 'warning',
-      message: `${gaps.length} requirement id(s) with no coverage or disposition: ${gaps.map((g) => g.id).join(', ')} — trace them, or record a status in the map \`requirements:\` section`,
-    });
+    gateR('matrix.gate-r.requirement-gap', `${gaps.length} requirement id(s) with no coverage or disposition: ${gaps.map((g) => g.id).join(', ')} — trace them, or record a status in the map \`requirements:\` section`);
   }
   // A `covered` claim with no traced variant is prose, not traceability: nothing
   // detects it when the proving scenario is later changed or deleted. Either tag
   // the scenario that proves it (`@spec:<id>`) or say where it IS covered.
   const unbacked = requirements.filter((r) => r.status === 'covered' && r.items.length === 0);
   if (unbacked.length > 0) {
-    findings.push({
-      gate: 'R', severity: 'warning',
-      message: `${unbacked.length} requirement id(s) declared \`covered\` with no variant tracing to them: ${unbacked.map((r) => r.id).join(', ')} — add \`@spec:<id>\` to the scenario that proves each, or use covered_elsewhere / partially_covered with a named reference`,
-    });
+    gateR('matrix.gate-r.covered-unbacked', `${unbacked.length} requirement id(s) declared \`covered\` with no variant tracing to them: ${unbacked.map((r) => r.id).join(', ')} — add \`@spec:<id>\` to the scenario that proves each, or use covered_elsewhere / partially_covered with a named reference`);
   }
 
   const variantCount = items.reduce((a, i) => a + i.variants.length, 0);

package/src/exporters/matrix/export.ts

@@ -28,6 +28,7 @@ import { renderMatrixCsv } from './render-csv';
 import { DeliveryMap, MatrixFinding, MatrixModel } from './types';
 import { ApiCatalogEntry } from '../types';
 import { RunEnvironment } from '../run-environment';
+import { GateRules } from '../../harness/gates/resolve-rule';
 
 export interface MatrixTargetPaths {
   cwd: string;
@@ -50,6 +51,8 @@ export interface MatrixTargetPaths {
   mapFile: string;
   /** Executor + environment of the run (#850) — absent for gates-only callers (inspect, approve). */
   runEnv?: RunEnvironment;
+  /** The unit's gate rules (catalog + gate-overrides) — absent means the catalog alone. */
+  gateRules?: GateRules;
 }
 
 function readSpecText(paths: MatrixTargetPaths): string {
@@ -94,6 +97,7 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
     apiCatalog: catalogFor(paths),
+    gateRules: paths.gateRules,
   });
   model.runEnv = paths.runEnv;
   // Perf verdict (#569): budgets are config (qa/perf.yaml), samples are the run's
@@ -132,6 +136,7 @@ export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): {
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
     apiCatalog,
+    gateRules: paths.gateRules,
   });
   const blocking = model.findings.filter((f) => f.severity === 'error');
   if (blocking.length > 0) return { findings: blocking, approved: [] };
@@ -164,7 +169,12 @@ export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): {
 
 export type MatrixFormat = 'xlsx' | 'csv' | 'both';
 
-/** Render + write the requested format(s). Caller has already enforced the gate policy. */
+/**
+ * Render + write the requested format(s). Caller has already enforced the gate policy. A draft (the
+ * matrix is not approved for official delivery: it carries the DRAFT banner) goes to its own
+ * `…-testcases.DRAFT.<ext>` and never overwrites the official file (#965); the tester's Manual results
+ * are still carried from the official workbook when it can be read.
+ */
 export async function writeMatrixDeliverables(
   paths: MatrixTargetPaths,
   model: MatrixModel,
@@ -174,23 +184,25 @@ export async function writeMatrixDeliverables(
 ): Promise<{ csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport }> {
   const out: { csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport } = {};
   const xlsx = format === 'xlsx' || format === 'both';
+  const draft = model.manifest.approvalState === 'draft';
   // Read the workbook about to be overwritten BEFORE writing anything, so the tester's Manual
   // results survive (#756) and a refusal leaves no half-written target behind.
   // A CSV-only export overwrites no workbook, so an unreadable one is no reason to refuse it — but a
   // readable one still holds the Manual results the CSV should show.
+  // A draft overwrites nothing official either, so an unreadable official workbook is no reason to refuse it.
   const prior = priorRead !== undefined ? priorRead
-    : xlsx ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit))
+    : xlsx && !draft ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit))
       : await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit)).catch(() => null);
   // Into the model first: the CSV, every cached total and roll-up, and the caller's summary
   // all read it (#891).
   applyManualCarry(model, prior);
   if (format === 'csv' || format === 'both') {
-    out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model));
+    out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model), undefined, { draft });
   }
   if (xlsx) {
     const wb = renderMatrixXlsx(model, getPackageVersion());
     out.manualCarry = carryManualResults(wb, model, prior);
-    out.xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb);
+    out.xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb, undefined, { draft });
   }
   return out;
 }