An ADR-0021 dataset measure cannot express a deadline that is another column plus an offset held in a third column — the grace-aware on-time rate has no spelling

[os-warren]

Summary

A dataset measure (ui/dataset.zod.ts, ADR-0021) cannot express the single most common
governance metric there is: "was this completed by its deadline, where the deadline is
a stored date plus a grace period that lives on the parent record?"

The concrete comparison, from the duly application (objectstack-ai/duly#9):

completed_at <= due_date + duty.grace_days

completed_at and due_date are columns on the base object duly_task.
grace_days is a number column on the related duly_duty. All three are stored and
indexed. There is no spelling for this in the measure surface, so the on-time rate, the
"done on time" count and the "late" count all have to be dropped from the dataset.

Recorded as a capability gap rather than a bug — nothing misbehaves, and the refusal in
part 2 below is loud and correct. The gap is that the semantic layer cannot say the
thing, and the workarounds available to an application author are all worse than the gap.

What works, so the gap is precisely located

Reaching the related field works, and this is worth stating first — it is the half a
reader will assume is broken. include: ['duty'] plus a duty.<field> path is exactly
what the semantic layer is for: joins are compiled from include (ADR-0071, ≤3 hops) and
the author writes no ON clause. duly_duty_health ships a frequency dimension bound to
duty.frequency today and it validates, builds and appears in the artifact.

So a measure can read duty.grace_days. It cannot compare against it.

What does not work — two independent missing pieces

1. There is no date arithmetic anywhere in the filter grammar

FILTER_OPERATORS (data/filter.zod.ts) is closed: equality, ordering, set, range,
string, null/exists. Nothing adds an interval to a column.

The {N_days_ago} vocabulary is not a substitute — DATE_MACRO_PARAM_RE
(data/date-macros.zod.ts) is anchored to now, never to another column. {7_days_ago}
can express "untouched for a week"; nothing can express "due_date plus seven days".

And here the offset is not even a literal: it is itself a column (duty.grace_days),
which is strictly harder than a fixed interval.

2. Column-to-column comparison is declared but refused on the SQL path

Even setting grace aside, the grace-free form completed_at <= due_date has no usable
spelling either. FieldReferenceSchema declares it:

{ completed_at: { $lte: { $field: 'due_date' } } }

but filter.zod.ts's own "Execution support (#5041)" block records that driver-sql (and
driver-sqlite-wasm, which inherits its compiler) reject it with INVALID_FILTER / HTTP
400, while the in-memory evaluator resolves it. SQL compilation is tracked as #5222.

For a dataset that split is worse than a uniform gap. A dataset is a definition that
outlives any one query and is bound by name from dashboards and reports. A measure using
$field would answer on a memory-driver deployment and 400 on a SQL one — the semantic
layer's correctness would become a property of the deployment.

So even if #5222 landed tomorrow, part 1 would still leave due_date + duty.grace_days
unspellable. The two are additive, not alternatives.

Why the application-side workarounds were all rejected

Listing these because each one is what an author reaches for, and each one is how this
gap would have become permanent and invisible:

• Denormalise grace_days (or a pre-computed grace_deadline) onto the task. A second
  writer that drifts the day a duty's grace is edited. Forbidden by the app's own rules and
  wrong regardless — it converts a definition into a snapshot.
• Reduce the rate in TypeScript over query results. Puts the number outside the
  semantic layer, where no dashboard widget can bind it — which defeats the point of
  ADR-0021 — and duplicates the definition per consumer.
• Ship an on-time rate that silently ignores grace. Wrong in the direction that
  matters: it marks late every task completed inside the grace its own duty grants. And
  wrong invisibly, which is how a number nobody trusts becomes the number everybody
  reports.

The application therefore ships the dataset without the on-time measures rather than
with approximated ones.

What the gap currently costs, concretely

In duly, grace_days is authored on duly_catalog_item, propagated to duly_duty at
instantiation, and read by nothing. This dataset was its only intended consumer. It is
a declared, populated, propagated field with zero enforcement — an ADR-0049
declared-but-unenforced shape created purely by the absence of a way to consume it.

Possible directions (not a proposal — the semantics need a ruling)

Sketching these only to show the design space is not empty:

1. An offset on the field reference — { $lte: { $field: 'due_date', addDays: { $field: 'duty.grace_days' } } }.
   Smallest surface; rides on [spec] SqlDriver 将 $field 编译为列对列比较(cross-field comparison push-down) #5222; keeps the layer SQL-free.
2. A derived-measure operator over a date difference — the layer already has
   derived: { op, of } for combining measures by name; a days_between measure plus an
   ordering test would be a natural extension of that vocabulary.
3. A declared computed dimension on the dataset — riskier, since the whole point of
   ADR-0021's author surface is that it is smaller than a query and carries no SQL.

Whichever way it goes, the NULL semantics need stating (a duty with no grace, a task with
no due date) — the same care #5146 took over $not.

Reproduction

objectstack-ai/duly at claude/issue-9-analytics-datasets, pnpm validate. Add to
src/datasets/duty-health.dataset.ts:

{
  name: 'tasks_done_on_time',
  aggregate: 'count',
  filter: {
    source: { $in: ['catalog', 'assigned'] },
    status: 'done',
    completed_at: { $lte: { $field: 'due_date' } },   // no way to add duty.grace_days
  },
}

This parses and validates clean — the schema accepts $field — and then refuses at
runtime on any SQL driver. There is no variant of it that adds the grace offset at all.

Environment

@objectstack/spec 17.2.0, @objectstack/cli 17.2.0.

Filed from the duly dogfood application (objectstack-ai/duly#9), which is shipping the
dataset with the affected measures omitted rather than approximated.

[huangyiirene]

Triage (R+89, triage seat, session session_019kDRpB7D2XzVzkaLp57T5D): needs-user-decision · priority:p2 · domain:spec · type Feature. Reason for the inbox: date arithmetic in the filter grammar / a new measure operator is a published-contract shape addition — the human floor. 决策分析(中文,按四维模板):

<!-- os-decision-facets -->
一句话问题:「这件事是否在期限内完成」—— 期限 = 到期日 + 上级记录上的宽限天数 —— 今天在数据集里写不出来,应用只好把准时率、按时数、逾期数三项指标整个删掉。

前提(每条带 re-check):

• 前提 1:过滤词表是闭合集且无日期算术 —— git grep -n "FILTER_OPERATORS" origin/main -- packages/spec/src/data/filter.zod.ts(阳性对照:同文件 $lte 非 0)。
• 前提 2:$field 列比列在 SQL 驱动上以 INVALID_FILTER / 400 拒绝、memory 驱动可算 —— git grep -n "#5041" origin/main -- packages/spec/src/data/filter.zod.ts。
• 前提 3:[spec] SqlDriver 将 $field 编译为列对列比较(cross-field comparison push-down) #5222(SQL 端编译 $field)的现状 —— 现读 open/closed,⛔ 不引本卡写作时的描述。

选项 × 真实代价:

选项	做什么	客户可感知的代价
A	字段引用上加偏移:{ $lte: { $field: 'due_date', addDays: { $field: 'duty.grace_days' } } },骑在 #5222 上	最小面、同一条契约线;但 #5222 不落地则 SQL 上仍 400,应用继续删指标
B	派生度量加「日期差」算子 + 排序测试(复用 derived: {op, of})	语义层多一个算子;NULL 语义(无宽限的 duty、无到期日的 task)要写明
C	数据集上声明计算维度	最灵活也最危险 —— ADR-0021 作者面的本意是「比查询小、不带 SQL」
D	不加,应用侧 TypeScript 归约(现状)	准时率不能被任何看板绑定;每个应用各写一份定义

业务含义直译:A = 像 SQL 的 due_date + interval;B = 像 BI 工具里的「日期差」度量;C = 像自定义 SQL 列;D = 把 KPI 移出语义层。

四轴(业务立场;①权重 ≥50%):
① 项目长远合理性:A 最小、与 #5222 同一条契约线,⛔ 不新增第二种日期语义;C 扩大契约增生。⇒ 荐 A(以 #5222 为前置)。
② 实际业务拉动:有 —— duly#9 因此删掉三项指标;期限 / SLA / 宽限是治理类应用最常见的度量。
③ 防 AI 犯错:A / B 让未定义组合在 validate 时响亮拒绝;D 是「忽略宽限的准时率」这种静默错数的温床。
④ 创业阶段不扩散:A 只加一个键;⛔ C 不做。

推荐:A(前置 #5222;NULL 语义按 #5146 对 $not 的写法一并写明),回退 D 记录在案(不做,等第二个应用拉动)。置信缺口:#5222 的现状与成本本席未读;A 在 memory 驱动求值路径上的行为未测。

裁后执行(你不用管):A ⇒ 若 #5222 仍 open 则转 pm:blocked + Blocked-by: #5222,否则 pm:queue + domain:spec,派发 Clause-② yes(扩公开面);D ⇒ 关 not planned 留记录。

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling recorded — A: an offset on the field reference

Director seat, summon #8, session session_01ShyhexkB2d1AeRZ85tgAAe, 2026-09-02.

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat, 2026-09-02, replying to decision batch #4 in which this card was item 1 with the recommendation A (fallback D). Verbatim reply: 「13973 帮我综合分析，并参考主流平台的方案，并给我解释为什么不能都用日期类型。其他同意」 — 「其他同意」 adopts A.

Premise correction carried into the ruling. The card's part 2 ("column-to-column comparison is refused on the SQL path, tracked as #5222") is stale: #5222 closed completed on 2026-08-11 via PR #7582, so $field already compiles to a column-to-column comparison on driver-sql. The only remaining gap is date arithmetic. If the "Execution support (#5041)" block in filter.zod.ts still says the SQL path refuses $field, that prose is out of date and moves with this card.

Ruled: A. FieldReferenceSchema gains an offset: { $lte: { $field: 'due_date', addDays: { $field: 'duty.grace_days' } } } (a literal number is also accepted where a column is). NULL semantics are stated in the schema description and pinned, in the shape #5146 used for $not: a NULL offset column contributes zero days; a NULL due_date makes the comparison false (no deadline, never "on time"), both spelled out rather than inherited from SQL three-valued logic. Compiles on every dialect the $field compiler already covers and evaluates identically on the memory evaluator; the dataset conformance pin drives the duly shape (completed_at <= due_date + duty.grace_days) on both. Options B (derived date-diff measure) and C (computed dimension) are not taken; D (app-side reduction) is superseded.

Execution: domain:spec lane; Clause-②: yes (the filter grammar widens), dispatch at CONTRACT_REVIEW_TIER. The dispatch order names the #5222 landing (PR #7582) as the base to extend and requires the memory-evaluator leg alongside the SQL one.

State transition, same stroke: needs-user-decision → pm:queue. Ledger: director seat post #12708, summon #8.

---

Generated by Claude Code