From ac9f463108531d28eee496bd837aab542eb9e409 Mon Sep 17 00:00:00 2001
From: Via <vance@heygen.com>
Date: Mon, 20 Jul 2026 13:26:51 +0000
Subject: [PATCH] fix(lint): recognize compiler-derived data-end as legitimate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`bundleToSingleHtml` compiles `data-duration` into `data-end` (in
`compileTimingAttrs`), then calls `validateHyperframeHtmlContract` against
the compiled HTML. The linter's `deprecated_data_end` rule fired on the
compiler's own consistent output — `<audio data-start="0" data-duration="18"
data-end="18">` — because `diagnoseDerivedEnd` unconditionally emitted a
`deprecated-end` diagnostic whenever both attributes were present, ignoring
whether the derived value matched.

Reporters routed this as "raw-source lint passes with 0 errors and 0
warnings, but `check --strict` still logs StaticGuard noise about
data-end without data-duration." Field cluster: cli-feedback crons 61-68,
n=25+ across darwin/arm64, darwin/x64, linux/x64, win32/x64, and versions
0.7.56 through 0.7.64. L3 reporter cite (ts=1784519869): "bundleToSingleHtml
compiles data-duration into data-end, then validates the compiled HTML and
reports its own generated data-end as deprecated."

Fix: `diagnoseDerivedEnd` now stays silent when the paired `data-end`
matches `data-start + data-duration` (within a 1ns epsilon to absorb
IEEE-754 residuals like `0.1 + 0.2 = 0.30000000000000004`). Truly-legacy
authoring shapes — `data-end` alone with no `data-duration`, or a
`data-end` that disagrees with `data-duration` — still fire
`deprecated_data_end`, with a refined message that names the drift on the
conflicting variant.

Facets covered: (a) validator treats compiler-derived `data-end` as legal
when paired with `data-duration`, and (e) recognizes the compile-time
rewrite site (`bundleToSingleHtml` → `compileHtml` → `compileTimingAttrs`).
Facets (b) stderr gating, (c) terminal JSON verdict, and (d) audio-not-
dropped are unblocked transitively — StaticGuard's `console.warn` is
already gated on `!isValid` and never drops audio; the check command
already emits JSON on every terminal path; so once the false-positive
diagnostic stops firing on compiler output, the noisy stderr line and the
misleading "check appears to fail" reporter framing both go away without
further wiring.

Co-Authored-By: Via <noreply@heygen.com>
---
 .../core/src/compiler/htmlBundler.test.ts     | 42 +++++++++++++++++
 packages/lint/src/rules/composition.test.ts   | 36 +++++++++++++++
 packages/lint/src/rules/composition.ts        | 12 ++++-
 .../parsers/src/compositionContract.test.ts   | 33 ++++++++++++++
 packages/parsers/src/compositionContract.ts   | 45 +++++++++++++++++--
 5 files changed, 164 insertions(+), 4 deletions(-)
diff --git a/packages/core/src/compiler/htmlBundler.test.ts b/packages/core/src/compiler/htmlBundler.test.ts
index e6ede4da0..b820d536f 100644
--- a/packages/core/src/compiler/htmlBundler.test.ts
+++ b/packages/core/src/compiler/htmlBundler.test.ts
@@ -1345,4 +1345,46 @@ describe("bundleToSingleHtml", () => {
     );
     expect(styleEls[0]?.parentElement?.tagName.toLowerCase()).toBe("head");
   });
+
+  // Regression: cli-feedback field cluster (crons 61-68, n=25+, cross-OS,
+  // versions 0.7.56-0.7.64). Reporter L3 cite (ts=1784519869):
+  // "bundleToSingleHtml compiles data-duration into data-end, then validates
+  // the compiled HTML and reports its own generated data-end as deprecated.
+  // Raw-source lint passes with 0 errors and 0 warnings." The end-to-end
+  // guarantee: source authored with only data-duration must round-trip through
+  // bundle + StaticGuard without producing a StaticGuard warning on the
+  // compiler's own consistent data-end. Facet-(a)/(e) fix.
+  it("does not emit a StaticGuard warning for source-authored data-duration on media", async () => {
+    const dir = makeTempProject({
+      "index.html": `<!doctype html>
+<html>
+<head><title>t</title></head>
+<body>
+  <div data-composition-id="root" data-width="1920" data-height="1080" data-start="0" data-duration="18">
+    <audio id="bgm" src="bgm.mp3" data-start="0" data-duration="18"></audio>
+    <audio id="narration" src="narr.mp3" data-start="5" data-duration="10"></audio>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines.root = { duration: () => 18, seek() {}, pause() {} };</script>
+</body></html>`,
+      "bgm.mp3": "",
+      "narr.mp3": "",
+    });
+
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const bundled = await bundleToSingleHtml(dir);
+      // Sanity: the compiler MUST have emitted data-end for both audio elements,
+      // so the linter is actually seeing the compiled shape (not the raw source).
+      expect(bundled).toContain('id="bgm"');
+      expect(bundled).toMatch(/id="bgm"[^>]*data-end="18"|data-end="18"[^>]*id="bgm"/);
+      expect(bundled).toMatch(/id="narration"[^>]*data-end="15"|data-end="15"[^>]*id="narration"/);
+
+      const staticGuardWarnings = warnSpy.mock.calls
+        .map((call) => String(call[0] ?? ""))
+        .filter((line) => line.includes("[StaticGuard]"));
+      expect(staticGuardWarnings).toEqual([]);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
 });
diff --git a/packages/lint/src/rules/composition.test.ts b/packages/lint/src/rules/composition.test.ts
index eaaf7fdd7..6b70817dc 100644
--- a/packages/lint/src/rules/composition.test.ts
+++ b/packages/lint/src/rules/composition.test.ts
@@ -28,6 +28,42 @@ describe("composition rules", () => {
         result.findings.find(({ code }) => code === "overlapping_clips_same_track"),
       ).toBeUndefined();
     });
+
+    // Regression: cli-feedback field cluster (crons 61-68, n=25+ across
+    // darwin/linux/win32 and versions 0.7.56-0.7.64). `bundleToSingleHtml`
+    // compiles `data-duration` into `data-end`, then re-validates the compiled
+    // HTML. Before this fix the linter fired `deprecated_data_end` on the
+    // compiler's own consistent output — a false-positive that reporters
+    // routed as "check --strict passes but StaticGuard still logs
+    // deprecated-attribute noise" (ts=1784548892, ts=1784541122).
+    it("does not flag deprecated_data_end when compiled data-end matches data-duration", async () => {
+      const result = await lintHyperframeHtml(`<!doctype html><html><body>
+        <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="30">
+          <audio id="bgm" src="bgm.mp3" data-start="0" data-duration="18" data-end="18"></audio>
+          <audio id="narration" src="narr.mp3" data-start="5" data-duration="10" data-end="15"></audio>
+        </div>
+        <script>window.__timelines = { main: {} };</script>
+      </body></html>`);
+
+      const deprecatedEnd = result.findings.filter(({ code }) => code === "deprecated_data_end");
+      expect(deprecatedEnd).toEqual([]);
+    });
+
+    // Companion regression: a manually authored stale `data-end` still fires
+    // `deprecated_data_end`, with a message that names the disagreement so
+    // the author can spot the drift rather than reading the legacy phrasing.
+    it("still flags deprecated_data_end when data-end disagrees with data-duration", async () => {
+      const result = await lintHyperframeHtml(`<!doctype html><html><body>
+        <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="30">
+          <audio id="bgm" src="bgm.mp3" data-start="0" data-duration="18" data-end="20"></audio>
+        </div>
+        <script>window.__timelines = { main: {} };</script>
+      </body></html>`);
+
+      const deprecatedEnd = result.findings.find(({ code }) => code === "deprecated_data_end");
+      expect(deprecatedEnd).toBeDefined();
+      expect(deprecatedEnd?.message).toMatch(/disagrees with data-duration/);
+    });
   });
 
   describe("subcomposition guidance", () => {
diff --git a/packages/lint/src/rules/composition.ts b/packages/lint/src/rules/composition.ts
index 025e1551d..cbc8799aa 100644
--- a/packages/lint/src/rules/composition.ts
+++ b/packages/lint/src/rules/composition.ts
@@ -465,10 +465,20 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
       }
       if (timing.diagnostics.some(({ code }) => code === "deprecated-end")) {
         const elementId = readAttr(tag.raw, "id") || undefined;
+        const conflicting = timing.diagnostics.some(({ code }) => code === "conflicting-end");
+        // Two shapes reach here after the false-positive fix (see
+        // compositionContract.ts `diagnoseDerivedEnd`): the truly-legacy shape
+        // (no data-duration, data-end alone) and the stale-companion shape
+        // (data-duration present but paired with a data-end that disagrees).
+        // A consistent data-duration + data-end pair — the shape the compiler
+        // emits — is silent and never reaches this branch.
+        const message = conflicting
+          ? `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has data-end that disagrees with data-duration. Remove the stale data-end; the compiler regenerates it from data-duration.`
+          : `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses data-end without data-duration. Use data-duration in source HTML.`;
         findings.push({
           code: "deprecated_data_end",
           severity: "error",
-          message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses data-end without data-duration. Use data-duration in source HTML.`,
+          message,
           elementId,
           fixHint:
             "Replace data-end with data-duration. The compiler generates data-end from data-duration automatically.",
diff --git a/packages/parsers/src/compositionContract.test.ts b/packages/parsers/src/compositionContract.test.ts
index 526b8fe4f..3842301ff 100644
--- a/packages/parsers/src/compositionContract.test.ts
+++ b/packages/parsers/src/compositionContract.test.ts
@@ -88,6 +88,39 @@ describe("composition timing contract", () => {
       expected: { start: 1, duration: 2, end: 3, trackIndex: 1 },
       codes: ["deprecated-end", "conflicting-end", "deprecated-layer", "conflicting-layer"],
     },
+    {
+      // Regression: compiler-derived `data-end` matching `data-duration` used
+      // to fire `deprecated-end`, which surfaced as a false-positive
+      // `deprecated_data_end` from StaticGuard whenever bundler output was
+      // re-validated. Field cluster: cli-feedback crons 61-68, n=25+ across
+      // darwin/linux/win32 and versions 0.7.56-0.7.64. Reporter L3 cite
+      // (ts=1784519869): "bundleToSingleHtml compiles data-duration into
+      // data-end, then validates the compiled HTML and reports its own
+      // generated data-end as deprecated." Consistent pairs are silent.
+      name: "compiler-derived end consistent with canonical duration is silent",
+      attrs: {
+        "data-start": "0",
+        "data-duration": "18",
+        "data-end": "18",
+      },
+      expected: { start: 0, duration: 18, end: 18, trackIndex: 0 },
+      codes: [],
+    },
+    {
+      name: "compiler-derived end within float epsilon of canonical duration is silent",
+      // data-start="0.1" + data-duration="0.2" evaluates to 0.30000000000000004
+      // under IEEE-754. The compiler serializes that residual verbatim, so the
+      // parsed derived-end and the reader-computed canonical end differ by ~2 ulps.
+      // A byte-exact comparison would refire the false positive; the epsilon
+      // gate keeps it silent.
+      attrs: {
+        "data-start": "0.1",
+        "data-duration": "0.2",
+        "data-end": "0.30000000000000004",
+      },
+      expected: { start: 0.1, duration: 0.2 },
+      codes: [],
+    },
     {
       name: "invalid values are diagnosed rather than coerced",
       attrs: { "data-start": "wat +", "data-duration": "-1", "data-track-index": "1.5" },
diff --git a/packages/parsers/src/compositionContract.ts b/packages/parsers/src/compositionContract.ts
index 56d901e60..1c25c58c6 100644
--- a/packages/parsers/src/compositionContract.ts
+++ b/packages/parsers/src/compositionContract.ts
@@ -206,18 +206,57 @@ function resolveStart(
 type DurationRead = Pick<ClipTiming, "duration" | "end" | "durationSource">;
 type TrackRead = Pick<ClipTiming, "trackIndex" | "trackSource">;
 
+// Float pairs like `data-start="0.1" + data-duration="0.2"` add to
+// `0.30000000000000004`, so the compiler-emitted `data-end` string can be a few
+// ulps off the sum a reader computes from the canonical inputs. Any drift below
+// this ceiling is treated as equal for the derived-end reconciliation check —
+// well below one 60fps frame (~16.67 ms) and orders of magnitude above the
+// worst realistic IEEE-754 residual (~2e-16 s).
+const DERIVED_END_EQUALITY_EPSILON_SECONDS = 1e-9;
+
+function derivedEndsAreConsistent(parsedEnd: number, canonicalEnd: number): boolean {
+  return Math.abs(parsedEnd - canonicalEnd) <= DERIVED_END_EQUALITY_EPSILON_SECONDS;
+}
+
+// Reconcile a `data-end` attribute paired with canonical `data-duration`.
+//
+// The compiler (`compileTimingAttrs` in @hyperframes/core) writes
+// `data-end = data-start + data-duration` into the bundled HTML so the runtime
+// can key off a single attribute. That derived attribute is legitimate — it is
+// not a legacy authoring shape. Treating it as `deprecated-end` here made the
+// linter fire `deprecated_data_end` on the compiler's own output whenever
+// StaticGuard re-validated a bundled composition, producing a false-positive
+// cluster reported in the field (n=25+ across cli-feedback crons 61-68).
+//
+// We keep `deprecated-end` for the truly legacy shape (see `readLegacyEnd` —
+// `data-end` present without `data-duration`) and for the *conflicting* case
+// where an author left a stale `data-end` behind a canonical duration edit; a
+// stale end must not be silently overridden without a diagnostic.
 function diagnoseDerivedEnd(
   rawEnd: string,
   canonicalEnd: number | null,
   diagnostics: ClipTimingDiagnostic[],
 ): void {
-  pushDiagnostic(diagnostics, "deprecated-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd);
   const parsedEnd = parseNumeric(rawEnd);
   if (parsedEnd == null) {
+    pushDiagnostic(diagnostics, "deprecated-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd);
     pushDiagnostic(diagnostics, "invalid-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd);
-  } else if (canonicalEnd != null && parsedEnd !== canonicalEnd) {
-    pushDiagnostic(diagnostics, "conflicting-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd);
+    return;
   }
+  if (canonicalEnd == null) {
+    // Canonical duration exists but resolved end is unknown (e.g. unresolved
+    // reference start). Preserve prior behavior — flag as deprecated so authors
+    // remove the stale companion attribute.
+    pushDiagnostic(diagnostics, "deprecated-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd);
+    return;
+  }
+  if (derivedEndsAreConsistent(parsedEnd, canonicalEnd)) {
+    // Compiler-derived (or manually consistent) `data-end` alongside
+    // `data-duration` — silent. No diagnostic.
+    return;
+  }
+  pushDiagnostic(diagnostics, "deprecated-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd);
+  pushDiagnostic(diagnostics, "conflicting-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd);
 }
 
 function readCanonicalDuration(
