@taopao/memoir 0.0.0-stage → 0.1.0

package/assets/migrations-pg/0159_fact_occurred_time.sql

@@ -0,0 +1,88 @@
+-- 仅 PostgreSQL：整理出的事实统一记录“发生时间”与“时间精度”。
+--
+-- 业务背景：
+--   整理聊天、录音时，每条分析结果都应能回答“这是什么时候发生/说出的”。此前只有事件、承诺、健康、
+--   付出等表有时间列，喜好、档案事实、心愿、礼物想法、待办、承诺核对只有“记录时间”或到天的日期；
+--   整理规则（common.md）又要求填 time_precision，但库里没有这一列。本迁移补齐。
+--
+-- 两列的含义（都允许为空：材料里推不出来就留空，不编造；旧数据不回填）：
+--   * occurred_at：发生或被说出的时刻，上海时间文本 'YYYY-MM-DD HH:MM:SS'。事后讲述的事要推算到真正发生的时间，
+--     不是消息发送时间，更不是入库时间；
+--   * time_precision：occurred_at（或该表既有的时间列）有多可信——
+--       exact       材料里明说了时刻；或记录的是“某句话说了什么”，时刻就是那条消息/录音的时间；
+--       approximate 记录的是“某件事发生了”，时刻只是从消息时间戳推出来的；
+--       date        只知道是哪一天（时刻部分不可信，可填当天 00:00:00 或留空 occurred_at）；
+--       month       只知道是哪个月（填当月 1 日）。
+--
+-- 范围：
+--   1. 已有完整时间列的表只补 time_precision：events（start_at）、promises（promised_at）、
+--      health_events（occurred_at）、giving_ledger（occurred_at）；
+--   2. 缺少时刻的表补 occurred_at + time_precision：preferences、profile_facts、wishes、gift_ideas、todos、promise_checks；
+--   3. 不动：important_dates（日期本身就是数据）、daily_presence（按天）、self_hypotheses（period_from/to）、
+--      relations（since_on/until_on）、intimacy_events（已有 time_known 表达“只知道日期”），
+--      以及订单、支付、银行流水等导入时自带时间的表。
+--
+-- 与既有列的关系：preferences.first_noted_on/last_noted_on 是“第一次/最后一次被提到的日期”，
+-- profile_facts.valid_from/valid_to 是“属性生效区间”，wishes.said_on 是说出的日期，这些语义不变；
+-- occurred_at 记的是这条记录对应的那一次发生/表述的时刻。
+--
+-- 兼容：只新增可空列，不改写已有数据，不回填历史行（历史行需要补时再另行授权）。
+SELECT pg_advisory_xact_lock(hashtext('relation-vault:write'));
+
+-- 1) 只补 time_precision：这些表已有自己的时间列，meaning 说明精度针对哪一列。
+DO $$
+DECLARE
+  item record;
+BEGIN
+  FOR item IN
+    SELECT * FROM (VALUES
+      ('events', 'start_at'),
+      ('promises', 'promised_at'),
+      ('health_events', 'occurred_at'),
+      ('giving_ledger', 'occurred_at')
+    ) AS t(table_name, time_column)
+  LOOP
+    EXECUTE format(
+      'ALTER TABLE public.%I ADD COLUMN IF NOT EXISTS time_precision text
+         CHECK (time_precision IS NULL OR time_precision IN (''exact'', ''approximate'', ''date'', ''month''))',
+      item.table_name);
+    EXECUTE format(
+      'COMMENT ON COLUMN public.%I.time_precision IS %L',
+      item.table_name,
+      format('时间精度（可空）：%s 有多可信。exact＝材料里明说了时刻，或记录的是“说了什么”而时刻就是消息时间；approximate＝记录的是“发生了什么”，时刻只是从消息时间推出来的；date＝只知道哪一天；month＝只知道哪个月；NULL＝未标注', item.time_column));
+  END LOOP;
+END $$;
+
+-- 2) 补 occurred_at + time_precision。
+DO $$
+DECLARE
+  item record;
+BEGIN
+  FOR item IN
+    SELECT * FROM (VALUES
+      ('preferences', '这条喜好/雷区被说出或观察到的时刻（first_noted_on/last_noted_on 只记被提到的日期）'),
+      ('profile_facts', '这条属性被说出或确认的时刻（valid_from/valid_to 是属性的生效区间，不等于说出的时刻）'),
+      ('wishes', '这个心愿被说出的时刻（said_on 只记日期）'),
+      ('gift_ideas', '这个礼物想法被提到的时刻'),
+      ('todos', '这条待办被提出的时刻（due_on 是截止日，done_at 是完成时刻）'),
+      ('promise_checks', '兑现情况被观察到的时刻（checked_on 只记核对日期）')
+    ) AS t(table_name, meaning)
+  LOOP
+    EXECUTE format(
+      'ALTER TABLE public.%I ADD COLUMN IF NOT EXISTS occurred_at text
+         CHECK (occurred_at IS NULL OR occurred_at ~ ''^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'')',
+      item.table_name);
+    EXECUTE format(
+      'ALTER TABLE public.%I ADD COLUMN IF NOT EXISTS time_precision text
+         CHECK (time_precision IS NULL OR time_precision IN (''exact'', ''approximate'', ''date'', ''month''))',
+      item.table_name);
+    EXECUTE format(
+      'COMMENT ON COLUMN public.%I.occurred_at IS %L',
+      item.table_name,
+      format('发生/说出时间（上海时间 YYYY-MM-DD HH:MM:SS，可空）：%s；事后讲述的要推算到真正发生的时刻，推算不出来留空，不是入库时间', item.meaning));
+    EXECUTE format(
+      'COMMENT ON COLUMN public.%I.time_precision IS %L',
+      item.table_name,
+      '时间精度（可空）：occurred_at 有多可信。exact＝材料里明说了时刻，或记录的是“说了什么”而时刻就是消息时间；approximate＝记录的是“发生了什么”，时刻只是从消息时间推出来的；date＝只知道哪一天；month＝只知道哪个月；NULL＝未标注');
+  END LOOP;
+END $$;

package/assets/migrations-pg/0160_agent_notes.sql

@@ -0,0 +1,118 @@
+-- 仅 PostgreSQL：把 Agent 写下的文字从日记表 journal_entries 拆到新表 agent_notes。
+--
+-- 业务背景（2026-11-10 用户要求）：
+--   日记是用户自己写的原始数据，只应有两类来源：网页手写（origin=h5）与旧仓库导入（legacy_md）。
+--   此前 Skill 的 remember 把每次附带的 text 存成一篇日记（origin=skill），Agent 也直接往日记表写过分析摘录，
+--   结果日记页、"今天"信息流、日历和检索里混进了"回复你的两个问题""修正某某笔误""9 月账单平台归属 1-20"这类
+--   给 Agent 的指令、Agent 的改动说明和分析过程。整理出来的结论应当是结构化行与 Wiki，这些文字两者都不是。
+--
+-- 拆分口径：
+--   1. 判定"Agent 写的"：origin='skill'，或 created_by 以 'skill:' / 'agent:' 开头（旧 Agent 协议的写入者）。
+--      用户手写与导入的日记 created_by 不会是这两种前缀；软删除的行一并搬走，保留原 deleted_at。
+--   2. 搬迁保留原 id、正文、时间与操作者，origin 改记为 remember（remember 的 text）或 agent（Agent 直接写入）。
+--      batch_id 取原日记插入时的审计批次（存在于 vault_batches 才填），用于把说明和那次写入对上。
+--   3. 证据链：指向这些行的 evidence_links(source_type='journal') 改为 source_type='user_stated'，source_key 不变（即 agent_notes.id）。
+--      'user_stated' 是 evidence_links 原有的取值（"用户亲口说的"），无需改约束。
+--   4. 检索索引 search_docs 中这些行的条目删除：Agent 记录不进日记，也不进全文检索；需要时用 SQL 直接查 agent_notes。
+--   5. vault_batches.journal_id 改名 note_id，值不变（同一 id 现在指向 agent_notes）。
+--   6. 日记表 origin 取值去掉 skill（搬迁后不再有此类行，Skill 也不再写日记）；cli 保留，代表用户经命令行写的日记。
+-- 只搬迁 Agent 写的行；用户日记的内容、id 与证据不变。搬迁与删除都经审计触发器留痕。
+SELECT pg_advisory_xact_lock(hashtext('relation-vault:write'));
+
+-- 1. 新表：Agent 记录。标准列与其他 Skill 表一致，经 vault_register_skill_table 挂写会话保护、审计与授权，
+--    remember 批次撤回时与同批其他写入一起还原。
+CREATE TABLE public.agent_notes (
+  id text PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  batch_id text REFERENCES public.vault_batches(id),
+  origin text NOT NULL DEFAULT 'remember' CHECK (origin IN ('remember', 'agent')),
+  about_person_id text REFERENCES public.persons(id),
+  written_at text NOT NULL DEFAULT public.vault_now_text(),
+  happened_on text CHECK (happened_on IS NULL OR happened_on ~ '^\d{4}-\d{2}-\d{2}$'),
+  title text NOT NULL,
+  content text NOT NULL,
+  sensitivity text NOT NULL DEFAULT 'normal' CHECK (sensitivity IN ('normal', 'private', 'intimate')),
+  provenance text CHECK (provenance IS NULL OR provenance IN ('user', 'inferred', 'import')),
+  created_at text NOT NULL DEFAULT public.vault_now_text(),
+  created_by text NOT NULL DEFAULT public.vault_current_actor(),
+  updated_at text NOT NULL DEFAULT public.vault_now_text(),
+  updated_by text NOT NULL DEFAULT public.vault_current_actor(),
+  deleted_at text
+);
+COMMENT ON TABLE public.agent_notes IS 'Agent 记录：remember 附带的文字（用户对 Agent 说的原话或本次改动说明）与 Agent 写下的过程说明；不是日记，不在日记页、信息流和检索中出现';
+COMMENT ON COLUMN public.agent_notes.id IS '行 ID（随机 UUID 文本）；evidence_links(source_type=user_stated) 的 source_key 指向它';
+COMMENT ON COLUMN public.agent_notes.batch_id IS '写入它的 Skill 批次（vault_batches.id），可空';
+COMMENT ON COLUMN public.agent_notes.origin IS 'remember=remember 的 text 自动保存，agent=Agent 直接写下的说明（旧版写在日记表里的分析摘录）';
+COMMENT ON COLUMN public.agent_notes.about_person_id IS '主要涉及的人物，可空';
+COMMENT ON COLUMN public.agent_notes.written_at IS '写下时间（上海时间）';
+COMMENT ON COLUMN public.agent_notes.happened_on IS '所说之事的发生日期 YYYY-MM-DD，可空';
+COMMENT ON COLUMN public.agent_notes.title IS '标题（默认取正文首行）';
+COMMENT ON COLUMN public.agent_notes.content IS '正文原文';
+COMMENT ON COLUMN public.agent_notes.sensitivity IS '敏感级别：normal/private/intimate';
+COMMENT ON COLUMN public.agent_notes.provenance IS '来源标记：user=用户亲口说的，inferred=Agent 推断，import=导入程序写入';
+COMMENT ON COLUMN public.agent_notes.created_at IS '创建时间（上海时间）';
+COMMENT ON COLUMN public.agent_notes.created_by IS '创建者';
+COMMENT ON COLUMN public.agent_notes.updated_at IS '更新时间（上海时间）';
+COMMENT ON COLUMN public.agent_notes.updated_by IS '更新者';
+COMMENT ON COLUMN public.agent_notes.deleted_at IS '软删除时间';
+CREATE INDEX ix_agent_notes_batch ON public.agent_notes(batch_id);
+CREATE INDEX ix_agent_notes_written ON public.agent_notes(written_at);
+SELECT public.vault_register_skill_table('agent_notes');
+
+-- 2. 搬迁 Agent 写的日记行。审计表只扫一次取各行的插入批次。
+CREATE TEMP TABLE moved_journal_notes ON COMMIT DROP AS
+  SELECT j.id
+    FROM public.journal_entries j
+   WHERE j.origin = 'skill' OR j.created_by LIKE 'skill:%' OR j.created_by LIKE 'agent:%';
+
+INSERT INTO public.agent_notes (
+  id, batch_id, origin, about_person_id, written_at, happened_on, title, content,
+  sensitivity, provenance, created_at, created_by, updated_at, updated_by, deleted_at
+)
+SELECT j.id,
+       b.id,
+       CASE WHEN j.origin = 'skill' THEN 'remember' ELSE 'agent' END,
+       j.about_person_id, j.written_at, j.happened_on, j.title, j.content,
+       j.sensitivity, j.provenance, j.created_at, j.created_by, j.updated_at, j.updated_by, j.deleted_at
+  FROM public.journal_entries j
+  JOIN moved_journal_notes m ON m.id = j.id
+  LEFT JOIN (
+    SELECT DISTINCT ON (a.primary_key_json::jsonb ->> 'id')
+           a.primary_key_json::jsonb ->> 'id' AS journal_id, a.change_set
+      FROM public.audit_log a
+     WHERE a.table_name = 'journal_entries' AND a.op = 'insert' AND a.change_set IS NOT NULL
+     ORDER BY a.primary_key_json::jsonb ->> 'id', a.id
+  ) ins ON ins.journal_id = j.id
+  LEFT JOIN public.vault_batches b ON b.id = ins.change_set;
+
+-- 3. 证据改指 agent_notes；检索索引移除；日记行删除（审计保留删除前全文）。
+UPDATE public.evidence_links e
+   SET source_type = 'user_stated'
+  FROM moved_journal_notes m
+ WHERE e.source_type = 'journal' AND e.source_key = m.id;
+
+DELETE FROM public.search_docs d
+ USING moved_journal_notes m
+ WHERE d.source_type = 'journal' AND d.source_key = m.id;
+
+DELETE FROM public.journal_entries j
+ USING moved_journal_notes m
+ WHERE j.id = m.id;
+
+-- 4. 批次表原话列改名。
+ALTER TABLE public.vault_batches RENAME COLUMN journal_id TO note_id;
+COMMENT ON COLUMN public.vault_batches.note_id IS '本批 remember 保存的 Agent 记录 ID（agent_notes.id）';
+
+-- 5. 日记 origin 去掉 skill；表注释改为当前口径。
+DO $$ DECLARE con text; BEGIN
+  SELECT k.conname INTO con
+    FROM pg_constraint k
+   WHERE k.conrelid = 'public.journal_entries'::regclass AND k.contype = 'c'
+     AND pg_get_constraintdef(k.oid) LIKE '%origin%legacy_md%';
+  IF con IS NOT NULL THEN
+    EXECUTE format('ALTER TABLE public.journal_entries DROP CONSTRAINT %I', con);
+  END IF;
+  ALTER TABLE public.journal_entries ADD CONSTRAINT journal_entries_origin_check
+    CHECK (origin IN ('h5', 'cli', 'legacy_md', 'ai_dictation'));
+END $$;
+COMMENT ON TABLE public.journal_entries IS '日记：用户自己写的原始数据（网页手写 h5、命令行 cli、旧仓库导入 legacy_md）；Agent 写的文字在 agent_notes，不写这里';
+COMMENT ON COLUMN public.journal_entries.origin IS 'h5=网页手写，cli=命令行写入，legacy_md=旧 Markdown 仓库导入，ai_dictation=语音口述';

package/assets/migrations-pg/0161_life_history.sql

@@ -0,0 +1,314 @@
+-- 仅 PostgreSQL：人生履历（工作、学历、居住）三张表，以及两项口径修正。
+--
+-- 业务背景（2026-11-10 用户访谈，方案 tmp/人生OS扩表方案.md §3.1）：
+--   项目定位为“人生 OS”，工作经历、学历和居住史是人生时间轴的骨架，收入、资产、证件等后续领域都会挂在上面。
+--   原先只有 Skill 运行时建的 housing_leases（仅租房），自有房、老家、宿舍放不进去；工作与学历只能散落在 profile_facts。
+--
+-- 共同口径：
+--   * 标准列与 0155 的知识表一致（status/confidence/sensitivity/note/provenance/created_*/updated_*/deleted_at），
+--     经 vault_register_skill_table 登记：写会话保护、逐行审计、整理批次可撤回；证据挂 evidence_links。
+--   * 每行都有 person_id（外键 persons），默认写本人；家人的履历同样可记。
+--   * 履历日期允许只到年或月（YYYY / YYYY-MM / YYYY-MM-DD）：人对多年前的入职、入学、搬家通常只记得到月份，
+--     强制精确到日只会逼写入方编造日期。文本按字典序比较即可排序；起止先后的 CHECK 把较长的一方截到较短的长度再比，
+--     这样“2020-05 入职、2020 离职”这种精度不同的写法不会被误拒。
+--   * 租约起止（lease_start_on/lease_end_on）是合同上的确切日期，沿用 housing_leases 的 YYYY-MM-DD。
+--
+-- 数据变动：
+--   1. housing_leases 若存在（只在用户正式库里由 Skill 运行时建过；全新库、演示库、测试库没有）：
+--      按原 id 复制进 residences，指向它的证据改指 residences，原表删除（不另存副本），
+--      原名改为只读兼容视图。已知影响：写过 housing_leases 的旧整理批次之后不能再整体撤回（撤回目标已是视图），用户已确认接受。
+--   2. intimacy_events 加 time_precision 并按 time_known 回填（见第 6 节）。
+--   3. v_typed_orders_explorer 补上停车订单（见第 7 节）。
+-- 不创建备份。
+SELECT pg_advisory_xact_lock(hashtext('relation-vault:write'));
+
+-- 履历日期：年、年月或年月日。
+CREATE OR REPLACE FUNCTION public.vault_is_partial_date(v text) RETURNS boolean
+  LANGUAGE sql IMMUTABLE AS $$ SELECT v ~ '^\d{4}(-\d{2}(-\d{2})?)?$' $$;
+COMMENT ON FUNCTION public.vault_is_partial_date(text) IS '履历类日期校验：允许 YYYY、YYYY-MM、YYYY-MM-DD 三种精度';
+
+-- 起止先后：较长的一方截到较短一方的长度再比较，精度不同时只比共同部分（“2020-05”起、“2020”止视为合法）。
+CREATE OR REPLACE FUNCTION public.vault_partial_date_le(a text, b text) RETURNS boolean
+  LANGUAGE sql IMMUTABLE AS $$
+    SELECT a IS NULL OR b IS NULL
+        OR left(a, least(length(a), length(b))) <= left(b, least(length(a), length(b)))
+  $$;
+COMMENT ON FUNCTION public.vault_partial_date_le(text, text) IS '履历类日期 a 不晚于 b（只比较两者共同精度的部分；任一为空视为成立）';
+
+-- 1. 工作经历：一段任职一行。换岗、升职若公司不变，按“一段任职”记一行，职位变化写 note 或另起一行均可，由写入方按事实拆。
+CREATE TABLE public.career_history (
+  id text PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  status text NOT NULL DEFAULT 'confirmed' CHECK (status IN ('proposed', 'confirmed', 'disputed', 'retired')),
+  confidence text NOT NULL DEFAULT 'high' CHECK (confidence IN ('high', 'medium', 'low')),
+  sensitivity text NOT NULL DEFAULT 'normal' CHECK (sensitivity IN ('normal', 'private', 'intimate')),
+  note text,
+  provenance text CHECK (provenance IS NULL OR provenance IN ('user', 'inferred', 'import')),
+  created_at text NOT NULL DEFAULT public.vault_now_text(),
+  created_by text NOT NULL DEFAULT public.vault_current_actor(),
+  updated_at text NOT NULL DEFAULT public.vault_now_text(),
+  updated_by text NOT NULL DEFAULT public.vault_current_actor(),
+  deleted_at text,
+  person_id text NOT NULL REFERENCES public.persons(id),
+  company text NOT NULL CHECK (btrim(company) <> ''),
+  department text,
+  title text,
+  grade text,
+  employment_type text NOT NULL DEFAULT 'full_time'
+    CHECK (employment_type IN ('full_time', 'intern', 'part_time', 'freelance', 'other')),
+  city text,
+  start_on text NOT NULL CHECK (public.vault_is_partial_date(start_on)),
+  end_on text CHECK (end_on IS NULL OR public.vault_is_partial_date(end_on)),
+  leave_reason text,
+  offer_monthly_cents bigint CHECK (offer_monthly_cents IS NULL OR offer_monthly_cents >= 0),
+  offer_months numeric(4, 1) CHECK (offer_months IS NULL OR offer_months > 0),
+  CHECK (public.vault_partial_date_le(start_on, end_on))
+);
+COMMENT ON TABLE public.career_history IS '工作经历：一段任职一行（公司、岗位、起止、offer 薪资）；实际到手收入另记，不在本表';
+COMMENT ON COLUMN public.career_history.person_id IS '任职的人，默认本人';
+COMMENT ON COLUMN public.career_history.company IS '公司或单位名称（原样记录，不缩写）';
+COMMENT ON COLUMN public.career_history.department IS '部门，可空';
+COMMENT ON COLUMN public.career_history.title IS '岗位或职位名称，可空';
+COMMENT ON COLUMN public.career_history.grade IS '职级（如 P6、T3-2），可空';
+COMMENT ON COLUMN public.career_history.employment_type IS 'full_time=全职，intern=实习，part_time=兼职，freelance=自由职业，other=其他';
+COMMENT ON COLUMN public.career_history.city IS '工作城市，可空';
+COMMENT ON COLUMN public.career_history.start_on IS '入职日期：YYYY、YYYY-MM 或 YYYY-MM-DD，只记得到月就写到月，不要补日';
+COMMENT ON COLUMN public.career_history.end_on IS '离职日期，精度同 start_on；仍在职为空';
+COMMENT ON COLUMN public.career_history.leave_reason IS '离职原因，可空';
+COMMENT ON COLUMN public.career_history.offer_monthly_cents IS 'offer 口径的税前月薪（分）；实际到手以收入记录为准';
+COMMENT ON COLUMN public.career_history.offer_months IS 'offer 口径每年发几个月（如 13、14.5）';
+CREATE INDEX ix_career_history_person ON public.career_history(person_id, start_on);
+
+-- 2. 学历：一段求学一行。
+CREATE TABLE public.education_history (
+  id text PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  status text NOT NULL DEFAULT 'confirmed' CHECK (status IN ('proposed', 'confirmed', 'disputed', 'retired')),
+  confidence text NOT NULL DEFAULT 'high' CHECK (confidence IN ('high', 'medium', 'low')),
+  sensitivity text NOT NULL DEFAULT 'normal' CHECK (sensitivity IN ('normal', 'private', 'intimate')),
+  note text,
+  provenance text CHECK (provenance IS NULL OR provenance IN ('user', 'inferred', 'import')),
+  created_at text NOT NULL DEFAULT public.vault_now_text(),
+  created_by text NOT NULL DEFAULT public.vault_current_actor(),
+  updated_at text NOT NULL DEFAULT public.vault_now_text(),
+  updated_by text NOT NULL DEFAULT public.vault_current_actor(),
+  deleted_at text,
+  person_id text NOT NULL REFERENCES public.persons(id),
+  school text NOT NULL CHECK (btrim(school) <> ''),
+  level text NOT NULL CHECK (level IN (
+    'primary', 'junior_high', 'senior_high', 'vocational', 'associate', 'bachelor', 'master', 'doctor', 'other'
+  )),
+  major text,
+  start_on text CHECK (start_on IS NULL OR public.vault_is_partial_date(start_on)),
+  end_on text CHECK (end_on IS NULL OR public.vault_is_partial_date(end_on)),
+  graduation_state text NOT NULL DEFAULT 'unknown'
+    CHECK (graduation_state IN ('graduated', 'studying', 'dropped', 'unknown')),
+  CHECK (public.vault_partial_date_le(start_on, end_on))
+);
+COMMENT ON TABLE public.education_history IS '学历：一段求学一行（学校、学历层次、专业、起止、是否毕业）';
+COMMENT ON COLUMN public.education_history.person_id IS '求学的人，默认本人';
+COMMENT ON COLUMN public.education_history.school IS '学校名称';
+COMMENT ON COLUMN public.education_history.level IS 'primary=小学，junior_high=初中，senior_high=高中，vocational=中专/职高，associate=大专，bachelor=本科，master=硕士，doctor=博士，other=其他';
+COMMENT ON COLUMN public.education_history.major IS '专业，可空';
+COMMENT ON COLUMN public.education_history.start_on IS '入学：YYYY、YYYY-MM 或 YYYY-MM-DD，可空';
+COMMENT ON COLUMN public.education_history.end_on IS '毕业或离校，精度同 start_on；在读为空';
+COMMENT ON COLUMN public.education_history.graduation_state IS 'graduated=已毕业，studying=在读，dropped=未完成，unknown=不清楚';
+CREATE INDEX ix_education_history_person ON public.education_history(person_id, start_on);
+
+-- 3. 居住史：住过的每一处一行，租房、自有房、老家、宿舍都算。
+--    同一处房子续租不另起一行（改 lease_end_on）；换房另起一行。
+CREATE TABLE public.residences (
+  id text PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  status text NOT NULL DEFAULT 'confirmed' CHECK (status IN ('proposed', 'confirmed', 'disputed', 'retired')),
+  confidence text NOT NULL DEFAULT 'high' CHECK (confidence IN ('high', 'medium', 'low')),
+  sensitivity text NOT NULL DEFAULT 'normal' CHECK (sensitivity IN ('normal', 'private', 'intimate')),
+  note text,
+  provenance text CHECK (provenance IS NULL OR provenance IN ('user', 'inferred', 'import')),
+  created_at text NOT NULL DEFAULT public.vault_now_text(),
+  created_by text NOT NULL DEFAULT public.vault_current_actor(),
+  updated_at text NOT NULL DEFAULT public.vault_now_text(),
+  updated_by text NOT NULL DEFAULT public.vault_current_actor(),
+  deleted_at text,
+  person_id text NOT NULL REFERENCES public.persons(id),
+  kind text NOT NULL CHECK (kind IN ('rent', 'owned', 'family_home', 'dorm', 'other')),
+  residence_state text NOT NULL CHECK (residence_state IN ('planned', 'current', 'ended')),
+  city text,
+  residence_name text,
+  address text,
+  move_in_on text CHECK (move_in_on IS NULL OR public.vault_is_partial_date(move_in_on)),
+  move_out_on text CHECK (move_out_on IS NULL OR public.vault_is_partial_date(move_out_on)),
+  lease_start_on text CHECK (lease_start_on IS NULL OR lease_start_on ~ '^\d{4}-\d{2}-\d{2}$'),
+  lease_end_on text CHECK (lease_end_on IS NULL OR lease_end_on ~ '^\d{4}-\d{2}-\d{2}$'),
+  landlord_person_id text REFERENCES public.persons(id),
+  landlord_or_agency text,
+  monthly_rent_cents bigint CHECK (monthly_rent_cents IS NULL OR monthly_rent_cents >= 0),
+  deposit_cents bigint CHECK (deposit_cents IS NULL OR deposit_cents >= 0),
+  payment_cycle text CHECK (payment_cycle IS NULL OR payment_cycle IN ('monthly', 'quarterly', 'half_yearly', 'yearly')),
+  -- 至少要知道“在哪”，否则这一行没有意义；地址不完整时只写城市或小区名，不要猜。
+  CHECK (coalesce(nullif(btrim(city), ''), nullif(btrim(residence_name), ''), nullif(btrim(address), '')) IS NOT NULL),
+  CHECK (public.vault_partial_date_le(move_in_on, move_out_on)),
+  CHECK (lease_start_on IS NULL OR lease_end_on IS NULL OR lease_start_on <= lease_end_on)
+);
+COMMENT ON TABLE public.residences IS '居住史：住过的每一处一行（租房、自有房、老家、宿舍），含租约与房东；取代 Skill 建的 housing_leases';
+COMMENT ON COLUMN public.residences.person_id IS '居住的人，默认本人';
+COMMENT ON COLUMN public.residences.kind IS 'rent=租房，owned=自有住房，family_home=父母家/老家，dorm=宿舍，other=其他';
+COMMENT ON COLUMN public.residences.residence_state IS 'planned=计划入住，current=正在住，ended=已搬离';
+COMMENT ON COLUMN public.residences.city IS '城市';
+COMMENT ON COLUMN public.residences.residence_name IS '小区、楼盘或宿舍名';
+COMMENT ON COLUMN public.residences.address IS '详细地址；不完整就留空，不要猜';
+COMMENT ON COLUMN public.residences.move_in_on IS '实际入住：YYYY、YYYY-MM 或 YYYY-MM-DD';
+COMMENT ON COLUMN public.residences.move_out_on IS '实际搬离，精度同 move_in_on；还在住为空';
+COMMENT ON COLUMN public.residences.lease_start_on IS '租约开始 YYYY-MM-DD（仅租房）';
+COMMENT ON COLUMN public.residences.lease_end_on IS '租约到期 YYYY-MM-DD（仅租房），续租时改这一列';
+COMMENT ON COLUMN public.residences.landlord_person_id IS '房东或管家在人物表中的 id；不是库里的人物时留空，写 landlord_or_agency';
+COMMENT ON COLUMN public.residences.landlord_or_agency IS '房东、管家或中介（文本）';
+COMMENT ON COLUMN public.residences.monthly_rent_cents IS '月租金（分）';
+COMMENT ON COLUMN public.residences.deposit_cents IS '押金（分）';
+COMMENT ON COLUMN public.residences.payment_cycle IS '付款周期：monthly=月付，quarterly=季付，half_yearly=半年付，yearly=年付';
+CREATE INDEX ix_residences_person ON public.residences(person_id, move_in_on);
+
+-- 4. 三张表共有的标准列注释与登记。
+DO $$ DECLARE tbl text; item record; BEGIN
+  FOREACH tbl IN ARRAY ARRAY['career_history', 'education_history', 'residences'] LOOP
+    FOR item IN SELECT * FROM (VALUES
+      ('id', '行 ID（随机 UUID 文本）'),
+      ('status', 'proposed=待确认，confirmed=已确认，disputed=用户提出异议，retired=已作废'),
+      ('confidence', '把握程度：high/medium/low'),
+      ('sensitivity', '敏感级别：normal/private/intimate'),
+      ('note', '备注'),
+      ('provenance', '来源标记：user=用户亲口说的，inferred=Agent 从聊天/录音等推断，import=导入程序写入'),
+      ('created_at', '创建时间（上海时间）'),
+      ('created_by', '创建者'),
+      ('updated_at', '更新时间（上海时间）'),
+      ('updated_by', '更新者'),
+      ('deleted_at', '软删除时间；撤回新增该行的批次时填写')
+    ) AS t(col, note)
+    LOOP
+      EXECUTE format('COMMENT ON COLUMN public.%I.%I IS %L', tbl, item.col, item.note);
+    END LOOP;
+    PERFORM public.vault_register_skill_table(tbl);
+  END LOOP;
+END $$;
+
+-- 5. housing_leases → residences（只在表真实存在且仍是普通表时执行；重复执行或全新库直接跳过）。
+DO $$
+BEGIN
+  IF (SELECT c.relkind FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE n.nspname = 'public' AND c.relname = 'housing_leases') IS DISTINCT FROM 'r' THEN
+    RETURN;
+  END IF;
+
+  -- 保留原 id：证据、审计与 Wiki 里引用的行 id 不变，只改表名。
+  -- status：active=正在住，ended=已搬离，planned=计划入住；原表没有入住/搬离日，租期原样搬到租约列。
+  -- 原表没有 deleted_at（运行时建表时漏了标准列），搬过来一律视为有效行。
+  EXECUTE $sql$
+    INSERT INTO public.residences (
+      id, note, provenance, created_at, created_by, updated_at, updated_by,
+      person_id, kind, residence_state, city, residence_name, address,
+      lease_start_on, lease_end_on, landlord_or_agency, monthly_rent_cents, deposit_cents, payment_cycle
+    )
+    SELECT id, note, provenance, created_at, created_by, updated_at, updated_by,
+           person_id, 'rent',
+           CASE status WHEN 'active' THEN 'current' WHEN 'planned' THEN 'planned' ELSE 'ended' END,
+           city, residence_name, address,
+           lease_start_on, lease_end_on, landlord_or_agency, monthly_rent_cents, deposit_cents, payment_cycle
+      FROM public.housing_leases
+  $sql$;
+
+  UPDATE public.evidence_links SET subject_table = 'residences' WHERE subject_table = 'housing_leases';
+
+  -- 不另存整表快照：正式迁移不附带备份或数据副本（AGENTS.md 备份执行约束）。原表每一列都已按原 id 搬进 residences，
+  -- status 的映射可逆（current↔active），插入也已逐行写进审计，删除原表不丢信息。
+  DROP TABLE public.housing_leases;
+
+  -- 兼容视图：旧查询与 Wiki 视图块里的 housing_leases 继续可读（只读，写入请改 residences）。
+  CREATE VIEW public.housing_leases AS
+    SELECT id, person_id, city, residence_name, address, landlord_or_agency,
+           monthly_rent_cents, deposit_cents, payment_cycle, lease_start_on, lease_end_on,
+           CASE residence_state WHEN 'current' THEN 'active' ELSE residence_state END AS status,
+           note, provenance, created_at, created_by, updated_at, updated_by
+      FROM public.residences
+     WHERE kind = 'rent' AND deleted_at IS NULL;
+  COMMENT ON VIEW public.housing_leases IS '只读兼容视图：租房记录已并入 residences（kind=rent），新写入请用 residences';
+  PERFORM public.vault_register_skill_view('housing_leases');
+END $$;
+
+-- 6. intimacy_events.time_precision：与 0159 其他事实表统一的“发生时间精度”。
+--    time_known 保留供现有网页与接口读取（1=知道具体时刻，0=只知道日期）。回填只做有把握的部分：
+--    time_known=0 → date；time_known=1 是建表默认值，无法区分“确实知道时刻”和“没填”，不回填为 exact，留空。
+--    之后写入方同时给两列时须一致：time_precision 为 date/month 时 time_known=0，为 exact/approximate 时 time_known=1。
+ALTER TABLE public.intimacy_events ADD COLUMN IF NOT EXISTS time_precision text
+  CHECK (time_precision IS NULL OR time_precision IN ('exact', 'approximate', 'date', 'month'));
+COMMENT ON COLUMN public.intimacy_events.time_precision IS
+  'occurred_at 的可信精度：exact=精确时刻，approximate=约略时刻，date=只知道日期，month=只知道月份；与 time_known 保持一致（date/month ↔ time_known=0）';
+UPDATE public.intimacy_events SET time_precision = 'date'
+ WHERE time_known = 0 AND time_precision IS NULL AND deleted_at IS NULL;
+
+-- 7. v_typed_orders_explorer 补停车：注释一直写着“外卖/团购/包裹/停车”，但定义里没有停车分支。
+--    停车记录（ext_parking_orders）挂在支付上（payment_platform + payment_txn_id），不在 orders 里，
+--    所以用 UNION ALL 追加一段：order_no 列放支付交易号，归属人取支付的 person_id。列名、列序与原视图一致。
+CREATE OR REPLACE VIEW public.v_typed_orders_explorer AS
+SELECT
+  o.platform,
+  o.order_no,
+  coalesce(o.paid_at, o.ordered_at) AS occurred_at,
+  round(o.total_paid_cents / 100.0, 2) AS amount_yuan,
+  o.status AS order_status,
+  CASE
+    WHEN t.order_no IS NOT NULL THEN '即时外卖'
+    WHEN v.order_no IS NOT NULL THEN '到店团购'
+    WHEN p.order_no IS NOT NULL THEN '电商快递'
+    WHEN o.shop_name = '火车票' THEN '城际高铁'
+    ELSE '其他消费'
+  END AS order_category,
+  CASE
+    WHEN t.order_no IS NOT NULL THEN concat_ws(' · 送至：', t.shop_branch, t.delivery_address)
+    WHEN v.order_no IS NOT NULL THEN concat_ws(' · ', v.applicable_mall, v.merchant_name)
+    WHEN p.order_no IS NOT NULL THEN concat_ws(' · 收件：', p.carrier, p.shipping_address)
+    WHEN o.shop_name = '火车票' THEN '京沪高铁沿线车站'
+    ELSE o.shop_name
+  END AS consumption_place,
+  CASE
+    WHEN t.order_no IS NOT NULL THEN t.shop_name
+    WHEN v.order_no IS NOT NULL THEN v.package_title
+    WHEN p.order_no IS NOT NULL THEN concat_ws(' ', p.goods_name, p.goods_spec)
+    WHEN o.shop_name = '火车票' THEN '12306 车票'
+    ELSE o.shop_name
+  END AS order_detail,
+  o.person_id AS owner_person_id
+FROM orders o
+LEFT JOIN ext_takeout_orders t ON t.order_platform = o.platform AND t.order_no = o.order_no
+LEFT JOIN ext_voucher_orders v ON v.order_platform = o.platform AND v.order_no = o.order_no
+LEFT JOIN ext_parcel_orders p ON p.order_platform = o.platform AND p.order_no = o.order_no
+UNION ALL
+SELECT
+  k.payment_platform,
+  k.payment_txn_id,
+  coalesce(k.entry_time, pay.occurred_at),
+  round(k.parking_fee_cents / 100.0, 2),
+  pay.status,
+  '车辆停放',
+  concat_ws(' · ', k.city, k.parking_lot_name),
+  concat_ws(' ', k.license_plate, CASE WHEN k.duration_minutes IS NOT NULL THEN k.duration_minutes || ' 分钟' END),
+  pay.person_id
+FROM ext_parking_orders k
+JOIN payments pay ON pay.platform = k.payment_platform AND pay.txn_id = k.payment_txn_id;
+COMMENT ON VIEW public.v_typed_orders_explorer IS
+  '按业务类型（外卖/团购/包裹/高铁/停车）浏览订单；停车来自 ext_parking_orders，挂在支付上，order_no 列为支付交易号';
+
+-- 8. 人生时间轴视图：工作、学历、居住合成一条，供 Skill 回答“那几年我在干什么、住哪”与 Wiki 视图块使用。
+CREATE VIEW public.v_life_timeline AS
+SELECT 'career'::text AS lane, id AS source_id, 'career_history'::text AS source_table, person_id,
+       concat_ws(' · ', company, title) AS title, concat_ws(' · ', department, city) AS detail,
+       start_on, end_on, (end_on IS NULL) AS ongoing
+  FROM public.career_history WHERE deleted_at IS NULL AND status <> 'retired'
+UNION ALL
+SELECT 'education', id, 'education_history', person_id,
+       concat_ws(' · ', school, major), level, start_on, end_on, graduation_state = 'studying'
+  FROM public.education_history WHERE deleted_at IS NULL AND status <> 'retired'
+UNION ALL
+SELECT 'residence', id, 'residences', person_id,
+       concat_ws(' · ', city, residence_name), kind, coalesce(move_in_on, lease_start_on),
+       coalesce(move_out_on, CASE WHEN residence_state = 'ended' THEN lease_end_on END), residence_state = 'current'
+  FROM public.residences WHERE deleted_at IS NULL AND status <> 'retired';
+COMMENT ON VIEW public.v_life_timeline IS
+  '人生时间轴：工作（career）、学历（education）、居住（residence）三条泳道合并；日期精度可能只到年或月，ongoing=仍在进行';
+SELECT public.vault_register_skill_view('v_life_timeline');