Skip to content

World's first open-source enterprise world model.

GitHub and Jira write their timestamps to the second (#691)

Royceba5f4b515bb2
diff --git a/README.md b/README.md
index 243696da..1a442341 100644
--- a/README.md
+++ b/README.md
@@ -110,7 +110,6 @@ cd web && pnpm install && pnpm dev
- [ ] **Execution gate**: checking an agent's calls against ontology rules and symbolic logic
- [ ] **MaxCompute**: mapping exploration and Ontology2SQL over Alibaba Cloud MaxCompute (Iceberg / Delta Lake via Trino, Databricks and Snowflake are in, awaiting a run against a real cluster)
- [ ] **More sources**: a ClickHouse driver; a Feishu connector
-- [ ] **Time to the moment**: an `instant` precision beside year / month / day, for sources that carry a real timestamp. Today a connector rounds it to a UTC day, which can shift an event across midnight by one day
- [ ] **Agent memory over MCP**: episode writes, the retrieve endpoint, and the MCP server
- [ ] **Enterprise**: OIDC SSO, backup and restore commands, benchmarks at 100k documents
diff --git a/crates/utopia-server/src/github_issues.rs b/crates/utopia-server/src/github_issues.rs
index aab33f4d..aabccbff 100644
--- a/crates/utopia-server/src/github_issues.rs
+++ b/crates/utopia-server/src/github_issues.rs
@@ -36,6 +36,7 @@
//! `pull_request` 字段区分。默认排除:问"工单系统"要的是工单。但留了开关——
//! 有些仓库(包括本仓库)的决策记录实际写在 PR 描述里。
+use crate::time_text;
use chrono::{DateTime, Utc};
use serde::Deserialize;
use std::collections::HashMap;
@@ -100,6 +101,11 @@ fn issue_number_from_url(url: &str) -> Option<i64> {
url.rsplit('/').next()?.parse().ok()
}
+/// 工单上的一个时刻,写进正文的样子:到秒、带 `Z`(`2026-08-18T16:18:27Z`)
+fn stamp(t: DateTime<Utc>) -> String {
+ time_text::world(t, Some("second"))
+}
+
/// 把一张工单连同它的评论与事件排成一篇文档。
///
/// **纯函数,不联网**——取回与组织分开,于是组织这一半测得动。
@@ -109,18 +115,22 @@ pub fn render(issue: &Issue, comments: &[&Comment], events: &[&Event]) -> String
out.push_str(&format!("# #{} {}\n\n", issue.number, issue.title));
// 抬头写成带日期的陈述句,而不是键值对:抽取器读的是句子。
- // "opened by X on 2026-08-18" 能抽出带 valid_from 的事实,
- // "created_at: 2026-08-18" 则要它自己去猜这是什么意思
+ // "opened by X on 2026-08-18T16:18:27Z" 能抽出带 valid_from 的事实,
+ // "created_at: 2026-08-18" 则要它自己去猜这是什么意思。
+ //
+ // **时间写到秒**(#691,0024 第 3 节):GitHub 给的是带 `Z` 的时刻,抽取器读回来就是
+ // second 精度。从前截到 UTC 的那一天,起点最多提前 24 小时,同一天的两件事还会被判成
+ // 同时发生的冲突。这不是开关——精度是数据自己的,截掉它等于替来源说「不知道几点」
if let Some(u) = &issue.user {
out.push_str(&format!(
"Opened by {} on {}.\n",
u.login,
- issue.created_at.format("%Y-%m-%d")
+ stamp(issue.created_at)
));
}
out.push_str(&format!("Currently {}.\n", issue.state));
if let Some(c) = issue.closed_at {
- out.push_str(&format!("Closed on {}.\n", c.format("%Y-%m-%d")));
+ out.push_str(&format!("Closed on {}.\n", stamp(c)));
}
if !issue.labels.is_empty() {
let names: Vec<&str> = issue.labels.iter().map(|l| l.name.as_str()).collect();
@@ -155,7 +165,7 @@ pub fn render(issue: &Issue, comments: &[&Comment], events: &[&Event]) -> String
};
out.push_str(&format!(
"- {} — {} by {}{}\n",
- e.created_at.format("%Y-%m-%d"),
+ stamp(e.created_at),
e.event,
who,
detail
@@ -174,7 +184,7 @@ pub fn render(issue: &Issue, comments: &[&Comment], events: &[&Event]) -> String
out.push_str(&format!(
"### {} on {}\n\n{}\n\n",
who,
- c.created_at.format("%Y-%m-%d"),
+ stamp(c.created_at),
body
));
}
@@ -307,21 +317,47 @@ mod tests {
.unwrap();
let out = render(&i, &[], &[&e1, &e2]);
- assert!(out.contains("Opened by Danmushu on 2026-08-18."), "{out}");
- assert!(out.contains("Closed on 2026-08-20."), "{out}");
+ assert!(
+ out.contains("Opened by Danmushu on 2026-08-18T16:18:27Z."),
+ "{out}"
+ );
+ assert!(out.contains("Closed on 2026-08-20T22:31:47Z."), "{out}");
assert!(out.contains("Labelled bug."), "{out}");
assert!(out.contains("Assigned to WaylandYang."), "{out}");
// 事件行带日期与执行者,labeled 还要带上是哪个标签
assert!(
- out.contains("- 2026-08-19 — labeled by WaylandYang (bug)"),
+ out.contains("- 2026-08-19T01:00:00Z — labeled by WaylandYang (bug)"),
"{out}"
);
assert!(
- out.contains("- 2026-08-20 — closed by WaylandYang"),
+ out.contains("- 2026-08-20T22:31:47Z — closed by WaylandYang"),
"{out}"
);
}
+ /// 正文里的时刻抽取器读得回来,而且是 second 精度:一件 UTC 23:59:59 发生的事,
+ /// 起点就是那一秒,不是那天的零点(#691)
+ #[test]
+ fn a_time_in_the_document_reads_back_to_the_second() {
+ let i = issue(serde_json::json!({
+ "number": 18, "title": "Anything", "state": "open",
+ "created_at": "2026-09-05T23:59:59Z", "updated_at": "2026-09-05T23:59:59Z",
+ "user": {"login": "x"}
+ }));
+ let c: Comment = serde_json::from_value(serde_json::json!({
+ "issue_url": "https://api.github.com/repos/x/y/issues/18",
+ "user": {"login": "x"}, "created_at": "2026-09-05T23:59:59Z", "body": "late"
+ }))
+ .unwrap();
+ let out = render(&i, &[&c], &[]);
+ let written = "2026-09-05T23:59:59Z";
+ assert!(out.contains(&format!("Opened by x on {written}.")), "{out}");
+ assert!(out.contains(&format!("### x on {written}")), "{out}");
+ let (at, precision) = utopia_extract::parse_time(written).expect("reads back");
+ assert_eq!(precision, "second");
+ assert_eq!(at, i.created_at);
+ }
+
/// 评论是**全仓库**取的,归拢必须按工单号,且按时间升序。
/// 归错了的后果很隐蔽:另一张工单的讨论出现在这张的正文里。
#[test]
@@ -442,7 +478,7 @@ mod tests {
issue.number
);
assert!(
- doc.contains(&issue.created_at.format("%Y-%m-%d").to_string()),
+ doc.contains(&super::stamp(issue.created_at)),
"#{} 正文里没有创建日期",
issue.number
);
diff --git a/crates/utopia-server/src/jira_issues.rs b/crates/utopia-server/src/jira_issues.rs
index ea26921a..e71fc57c 100644
--- a/crates/utopia-server/src/jira_issues.rs
+++ b/crates/utopia-server/src/jira_issues.rs
@@ -167,14 +167,16 @@ pub fn render(issue: &Issue) -> String {
));
// 抬头写成带日期的陈述句,不是键值对:抽取器读的是句子,
- // "Reported by X on 2026-08-24" 能抽出带 valid_from 的事实
+ // "Reported by X on 2026-08-24T11:11:52Z" 能抽出带 valid_from 的事实。
+ // 时间写到秒、带 `Z`(#691,0024 第 3 节),与 GitHub 那边同一个写法;
+ // Jira 给的毫秒不写,抽取器也只认到秒
if let (Some(r), Some(c)) = (&f.reporter, &f.created) {
out.push_str(&format!(
"Reported by {} on {}.\n",
who(&Some(User {
display_name: r.display_name.clone()
})),
- c.0.format("%Y-%m-%d")
+ stamp(c.0)
));
}
if let Some(t) = name(&f.issuetype) {
@@ -193,7 +195,7 @@ pub fn render(issue: &Issue) -> String {
));
}
if let Some(r) = &f.resolutiondate {
- out.push_str(&format!("Resolved on {}.\n", r.0.format("%Y-%m-%d")));
+ out.push_str(&format!("Resolved on {}.\n", stamp(r.0)));
}
if !f.labels.is_empty() {
out.push_str(&format!("Labelled {}.\n", f.labels.join(", ")));
@@ -225,7 +227,7 @@ pub fn render(issue: &Issue) -> String {
at.0,
format!(
"- {} — {} changed {field}: {from} → {to}\n",
- at.0.format("%Y-%m-%d"),
+ stamp(at.0),
who(&h.author),
),
));
@@ -252,10 +254,7 @@ pub fn render(issue: &Issue) -> String {
if body.is_empty() {
continue;
}
- let at = c
- .created
- .map(|t| t.0.format("%Y-%m-%d").to_string())
- .unwrap_or_else(|| "?".into());
+ let at = c.created.map(|t| stamp(t.0)).unwrap_or_else(|| "?".into());
out.push_str(&format!("### {} on {}\n\n{}\n\n", who(&c.author), at, body));
}
}
@@ -330,6 +329,11 @@ pub async fn fetch_all(
Ok((out, total))
}
+/// 工单上的一个时刻,写进正文的样子:到秒、带 `Z`
+fn stamp(t: DateTime<Utc>) -> String {
+ crate::time_text::world(t, Some("second"))
+}
+
#[cfg(test)]
mod tests {
use super::*;
@@ -393,6 +397,30 @@ mod tests {
assert!(doc.contains(" → "), "缺少 from → to:{doc}");
}
+ /// 正文里的时刻写到秒、带 `Z`,毫秒不写;抽取器读回来是 second 精度(#691)
+ #[test]
+ fn a_time_in_the_document_is_written_to_the_second() {
+ let issue: Issue = serde_json::from_value(serde_json::json!({
+ "key": "X-2",
+ "fields": {
+ "summary": "t", "description": null, "labels": [],
+ "reporter": {"displayName": "Mickael"},
+ "created": "2026-08-24T23:59:59.944+0000",
+ "updated": "2026-08-25T00:00:00.000+0000",
+ "resolutiondate": "2026-08-25T08:30:00.123+0800"
+ }
+ }))
+ .unwrap();
+ let out = render(&issue);
+ assert!(
+ out.contains("Reported by Mickael on 2026-08-24T23:59:59Z."),
+ "{out}"
+ );
+ assert!(out.contains("Resolved on 2026-08-25T00:30:00Z."), "{out}");
+ let (_, precision) = utopia_extract::parse_time("2026-08-24T23:59:59Z").unwrap();
+ assert_eq!(precision, "second");
+ }
+
/// 空评论不该留下一个只有标题的空节(与 GitHub 那边同一个口径)。
#[test]
fn an_empty_comment_leaves_no_stub() {
diff --git a/docs/decisions/0013-a-source-should-hand-over-its-history.md b/docs/decisions/0013-a-source-should-hand-over-its-history.md
index ef7f42ce..e043e7db 100644
--- a/docs/decisions/0013-a-source-should-hand-over-its-history.md
+++ b/docs/decisions/0013-a-source-should-hand-over-its-history.md
@@ -1,6 +1,6 @@
# 0013 · A source hands over its history
-- **Status**: implemented for `github_issues` (#134), `jira_issues` (#135) and `notion` (#213, pages keep their own clock); WebDAV shares and object storage (S3 / Azure / GCS) arrived as plain file sources (#200, #207, #209) · Feishu and Confluence not started · the `instant` precision has not been triggered
+- **Status**: implemented for `github_issues` (#134), `jira_issues` (#135) and `notion` (#213, pages keep their own clock); WebDAV shares and object storage (S3 / Azure / GCS) arrived as plain file sources (#200, #207, #209) · Feishu and Confluence not started · GitHub and Jira write their timestamps to the second (#691, per 0024 §3)
- **Written**: 2026-08-31 · condensed into English 2026-09-03
- **Related**: the bitemporal ground of [0001](0001-ontology-import-and-governance.md); the same judgment on the corpus side in `scripts/bench/fetch-wiki-history.mjs` (#122); [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) is the other end of the line — this record is about how things come in, that one about the rules they land by; the grant layer added afterwards (#142, `data_source_grants`) decides who may mount a source: provenance visible, destination governed
@@ -64,6 +64,20 @@ Wikipedia; there revisions have to be sampled, an issue tracker hands the events
and rendering branch together) only when someone needs local business days or a source
whose events cluster around midnight.
+ *Revised 2026-09-14 (#691):* the three pieces this waited for all landed in 0024: the
+ precision ladder and truncation CHECK, the prompt sentence about zoned clock times, and the
+ rendering branch in `time_text::world`. 0024 §3 names a ticket's `updated_at` as a time that
+ reaches the second. So the GitHub and Jira connectors now write `2026-08-18T16:18:27Z`, and
+ the extractor reads it back at second precision. Cutting to the day had two real costs that
+ the paragraph above missed. A start could move up to 24 hours early. Two events on the same
+ UTC day could be recorded as a simultaneous conflict. The "off by one day for a UTC+8 reader"
+ framing was wrong: world time renders in UTC at every precision (next paragraph), so no
+ reader sees a shifted date. No per-source setting was added; precision belongs to the data.
+ Already-ingested day-precision facts are left alone: "the day is known" is still true of
+ them, and an issue that changes again is re-rendered on its next sync. The document date in
+ the extraction prompt (`Document date:`) stays a day. It anchors relative phrases like "last
+ March", and the full instant is already stored in `documents.doc_time`.
+
A related rule is already in code: world time and record time get opposite timezone
treatment. `valid_from` / `valid_to` are calendar dates from statements in documents and
render in UTC (local conversion shows a UTC-5 reader the previous day); `recorded_at` is a
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index 40ea635b..b2f0bfb6 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -36,7 +36,7 @@ The test for writing one: if someone (including us) looks at a piece of code in
| 0010 | [An unnamed relation stays empty](0010-no-relation-is-no-relation.md) | Implemented · `predicate_id` nullable, `related_to` gone, wording recovered by `fact_surface_predicate` · follow-ups done with 0011 |
| 0011 | [A mapping is configuration](0011-a-mapping-is-not-a-fact.md) | Implemented (#126 / #140 / #148) · Review flow and revision history rebuilt · the evidence chain not built · revised in part by 0036: the concept becomes an attribute or a rule, the table becomes a rendered one |
| 0012 | [The ontology is a contract](0012-the-ontology-is-a-contract-not-a-suggestion.md) | Implemented · violation rate 57% → 4%, reversals 39 → 0 · guard extended to adoption and merge (#190 / #196) · reified-shell filter at pack import open |
-| 0013 | [A source hands over its history](0013-a-source-should-hand-over-its-history.md) | Implemented for GitHub, Jira and Notion (#134 / #135 / #213) · Feishu and Confluence not started · `instant` precision not triggered |
+| 0013 | [A source hands over its history](0013-a-source-should-hand-over-its-history.md) | Implemented for GitHub, Jira and Notion (#134 / #135 / #213) · Feishu and Confluence not started · GitHub and Jira timestamps written to the second (#691) |
| 0014 | [Identity from the person, scope from the token](0014-identity-from-the-person-scope-from-the-token.md) | Implemented (#180) · five read-only MCP tools over Streamable HTTP · tokens page at `/account/tokens` · `can_write` still hard-coded false |
| 0015 | [A recorded sentence waits for a nod](0015-recording-a-sentence-is-not-asserting-a-fact.md) | Implemented · memory facts wait in `pending_facts`, nod queue and chat card, `remember` reopened · MCP write is the next cut |
| 0016 | [Close the open seams before cutting new ones](0016-close-the-open-seams-before-cutting-new-ones.md) | In progress · A done · B done (B4 deferred) · C1 done (#289) · C2 done (#297) · C3–C5 open · D2 worked around (#231); the lakehouse landed ahead of D4 (#239) |