@things-factory/ai-dashboard 10.1.213 → 10.1.215

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-dashboard",
-  "version": "10.1.213",
+  "version": "10.1.215",
   "main": "dist-server/index.js",
   "browser": "dist-client/index.js",
   "things-factory": true,
@@ -33,9 +33,9 @@
     "@operato/popup": "^10.29.39",
     "@operato/shell": "^10.29.39",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-assistant": "^10.1.213",
-    "@things-factory/ai-client-base": "^10.1.213",
-    "@things-factory/auth-base": "^10.1.213",
+    "@things-factory/ai-assistant": "^10.1.215",
+    "@things-factory/ai-client-base": "^10.1.215",
+    "@things-factory/auth-base": "^10.1.215",
     "@things-factory/env": "^10.1.149",
     "@things-factory/shell": "^10.1.208",
     "graphql-scalars": "^1.22.0",
@@ -45,5 +45,5 @@
   "devDependencies": {
     "copyfiles": "^2.4.1"
   },
-  "gitHead": "81f23aa18cb584c7d8185e81cca0d688f509cf8c"
+  "gitHead": "7de5e80eb1f4e2e268746aee39f820e7563f454d"
 }

package/server/service/card/card-access.test.ts

@@ -5,7 +5,9 @@ import { listReadTarget, type DetailRead } from '@things-factory/ai-assistant'
 
 import { cardAccessOf, departmentsOfEmployees, shareRefusal } from './card-access'
 import { findCardProposal } from './card-proposal'
-import { proposeDashboardCard } from './card-tool'
+import { proposeDashboardCard, readDashboardCard } from './card-tool'
+import { CARD_AXIS } from './card-names'
+import { CARD_AXIS as CLIENT_AXIS, cardSelection } from '../../../client/utils/card-words'
 
 const viewer = { userId: 'u-me', domainId: 'd1', departmentIds: ['dep-sales'] }
 
@@ -20,6 +22,16 @@ describe('who may use a card', () => {
     expect(cardAccessOf({ ownerId: 'u-x', domainId: 'd1' }, viewer, [{ scope: 'DOMAIN', targetId: 'd1' }])).toBe('shared')
   })
 
+  it('★ a role share reaches whoever holds that role in the domain, and no one else', () => {
+    const holder = { ...viewer, roleIds: ['role-hr'] }
+    expect(cardAccessOf({ ownerId: 'u-x', domainId: 'd1' }, holder, [{ scope: 'ROLE', targetId: 'role-hr' }])).toBe('shared')
+    expect(cardAccessOf({ ownerId: 'u-x', domainId: 'd1' }, holder, [{ scope: 'ROLE', targetId: 'role-finance' }])).toBeUndefined()
+    expect(cardAccessOf({ ownerId: 'u-x', domainId: 'd1' }, viewer, [{ scope: 'ROLE', targetId: 'role-hr' }])).toBeUndefined()
+    /* A role of the domain is given; one it does not have is refused. */
+    expect(shareRefusal({ scope: 'ROLE', targetId: 'role-hr' }, { domainId: 'd1', departmentsAvailable: true, roleIds: ['role-hr'] })).toBeUndefined()
+    expect(shareRefusal({ scope: 'ROLE', targetId: 'role-other' }, { domainId: 'd1', departmentsAvailable: true, roleIds: ['role-hr'] })).toBe('unknown-role')
+  })
+
   it('★ never across domains - not even its owner in another domain', () => {
     expect(cardAccessOf({ ownerId: 'u-me', domainId: 'd2' }, viewer, [])).toBeUndefined()
     expect(cardAccessOf({ ownerId: 'u-x', domainId: 'd2' }, viewer, [{ scope: 'DOMAIN', targetId: 'd2' }])).toBeUndefined()
@@ -105,7 +117,18 @@ describe('the card tool', () => {
     expect(result).toMatchObject({ rejected: true, error: 'definition-unfit' })
     expect(result.source.columns.map((one: any) => one.name)).toEqual(['customer', 'currency', 'remaining'])
     const unknown: any = await proposeDashboardCard({ ...args, source: { read: 'office.nope' } }, context, deps)
-    expect(unknown).toMatchObject({ rejected: true, error: 'unknown-read', sources: ['office.receivables/by-contract'] })
+    expect(unknown).toMatchObject({ rejected: true, error: 'unknown-read', sources: [{ read: 'office.receivables', list: 'by-contract', tool: 'readOfficeReceivables' }] })
+  })
+
+  it('★ a read named by its tool is that read, and a field left empty is no field', async () => {
+    const result: any = await proposeDashboardCard(
+      { ...args, source: { read: 'readOfficeReceivables', where: { direction: 'SALES', staleDays: null } }, rows: { groupBy: 'customer', sortBy: 'remaining', desc: true, limit: 5, match: null } },
+      context,
+      deps
+    )
+    expect(result).toMatchObject({ proposed: true })
+    expect(result.card.definition.source).toEqual({ read: 'office.receivables', where: { direction: 'SALES' } })
+    expect(result.card.definition.rows).toEqual({ groupBy: 'customer', sortBy: 'remaining', desc: true, limit: 5 })
   })
 
   it('★ bars whose names repeat are sent back to be grouped - one name, one bar', async () => {
@@ -128,11 +151,43 @@ describe('the card tool', () => {
     expect(result).toMatchObject({ rejected: true, error: 'door-closed' })
   })
 
+  const C1 = '75e8d067-62e6-47f5-9c2f-bf10b6b97b83'
+  const C2 = 'f9e3afc2-2d80-4ce9-99ca-b3e628a66f02'
+  const C9 = '00000000-0000-4000-8000-000000000009'
+
   it('★ a change is of one\'s own card, from its current version', async () => {
-    const cardOf = async (id: string) => (id === 'c1' ? { ownerId: 'u-me', version: 3 } : id === 'c2' ? { ownerId: 'u-x', version: 1 } : undefined)
-    expect(await proposeDashboardCard({ ...args, cardId: 'c1' }, context, { ...deps, cardOf })).toMatchObject({ proposed: true, card: { cardId: 'c1', baseVersion: 3 } })
-    expect(await proposeDashboardCard({ ...args, cardId: 'c1', baseVersion: 2 }, context, { ...deps, cardOf })).toMatchObject({ rejected: true, error: 'stale-version', current: 3 })
-    expect(await proposeDashboardCard({ ...args, cardId: 'c2' }, context, { ...deps, cardOf })).toMatchObject({ rejected: true, error: 'not-your-card' })
-    expect(await proposeDashboardCard({ ...args, cardId: 'c9' }, context, { ...deps, cardOf })).toMatchObject({ rejected: true, error: 'unknown-card' })
+    const cardOf = async (id: string) => (id === C1 ? { ownerId: 'u-me', version: 3 } : id === C2 ? { ownerId: 'u-x', version: 1 } : undefined)
+    expect(await proposeDashboardCard({ ...args, cardId: C1 }, context, { ...deps, cardOf })).toMatchObject({ proposed: true, card: { cardId: C1, baseVersion: 3 } })
+    expect(await proposeDashboardCard({ ...args, cardId: C1, baseVersion: 2 }, context, { ...deps, cardOf })).toMatchObject({ rejected: true, error: 'stale-version', current: 3 })
+    expect(await proposeDashboardCard({ ...args, cardId: C2 }, context, { ...deps, cardOf })).toMatchObject({ rejected: true, error: 'not-your-card' })
+    expect(await proposeDashboardCard({ ...args, cardId: C9 }, context, { ...deps, cardOf })).toMatchObject({ rejected: true, error: 'unknown-card' })
+  })
+
+  it('★ a picked card is named by its key dashboard-card:<uuid> - read and changed by it; anything else is never looked up', async () => {
+    const looked: string[] = []
+    const cardOf = async (id: string) => (looked.push(id), id === C1 ? { ownerId: 'u-me', version: 3 } : undefined)
+    /* The key the dashboard hands (card-words cardSelection) is the card. */
+    const key = cardSelection({ id: C1, name: '미수금' }, '나의 대시보드').records[0].id
+    expect(key).toBe(`dashboard-card:${C1}`)
+    expect(await proposeDashboardCard({ ...args, cardId: key }, context, { ...deps, cardOf })).toMatchObject({ proposed: true, card: { cardId: C1, baseVersion: 3 } })
+    /* A list name, another record's key or a name is no card - said, never handed to the database (a uuid column refuses it). */
+    for (const wrong of [`dashboardCards:${C1}`, `contract:${C1}`, '미수금 상위 5곳']) {
+      expect(await proposeDashboardCard({ ...args, cardId: wrong }, context, { ...deps, cardOf })).toMatchObject({ rejected: true, error: 'card-id-unreadable' })
+    }
+    expect(looked).toEqual([C1])
+    const read = async (id: string) => (looked.push(id), id === C1 ? { card: { id: C1, name: '미수금', version: 3, definition: {} }, access: 'owner' } : {})
+    expect(await readDashboardCard({ id: key }, context, read)).toMatchObject({ id: C1, version: 3, access: 'owner' })
+    expect(await readDashboardCard({ id: 'dashboardCards' }, context, read)).toMatchObject({ rejected: true, error: 'card-id-unreadable' })
+    expect(looked).toEqual([C1, C1])
+  })
+
+  it('★ on the dashboard, what the person asks to see ends in a card - not a figure in words', () => {
+    const { turnSystemPrompt } = require('@things-factory/ai-assistant')
+    expect(turnSystemPrompt('persona', { page: 'my-dashboard' })).toMatch(/end the turn with proposeDashboardCard/)
+    expect(turnSystemPrompt('persona', { page: 'receivable-page' })).toBe('persona')
+  })
+
+  it('the client hands a card by the axis the server reads', () => {
+    expect(CLIENT_AXIS).toBe(CARD_AXIS)
   })
 })

package/server/service/card/card-access.ts

@@ -10,7 +10,7 @@
 export type CardAccess = 'owner' | 'shared'
 
 export interface CardShareRow {
-  scope: 'USER' | 'DEPARTMENT' | 'DOMAIN' | string
+  scope: 'USER' | 'DEPARTMENT' | 'ROLE' | 'DOMAIN' | string
   targetId: string
 }
 
@@ -19,6 +19,8 @@ export interface CardViewer {
   domainId: string
   /** The departments of the viewer's active employee records - none where the organization module is not there. */
   departmentIds: readonly string[]
+  /** The roles the viewer holds in the domain, the ones it inherits included - a role share reaches whoever holds it. */
+  roleIds?: readonly string[]
 }
 
 export function cardAccessOf(card: { ownerId?: string | null; domainId?: string | null }, viewer: CardViewer, shares: readonly CardShareRow[]): CardAccess | undefined {
@@ -28,7 +30,8 @@ export function cardAccessOf(card: { ownerId?: string | null; domainId?: string
     share =>
       (share.scope === 'USER' && share.targetId === viewer.userId) ||
       (share.scope === 'DOMAIN' && share.targetId === viewer.domainId) ||
-      (share.scope === 'DEPARTMENT' && viewer.departmentIds.includes(share.targetId))
+      (share.scope === 'DEPARTMENT' && viewer.departmentIds.includes(share.targetId)) ||
+      (share.scope === 'ROLE' && (viewer.roleIds ?? []).includes(share.targetId))
   )
   return shared ? 'shared' : undefined
 }
@@ -43,11 +46,15 @@ export function departmentsOfEmployees(records: readonly { active?: boolean | nu
   return [...new Set((records ?? []).filter(one => one?.active === true && one.department?.id).map(one => one.department!.id!))]
 }
 
-/** A share the owner may give - a known scope with a target; the domain scope names the owner's own domain. */
-export function shareRefusal(share: CardShareRow, owner: { domainId: string; departmentsAvailable: boolean }): string | undefined {
-  if (!['USER', 'DEPARTMENT', 'DOMAIN'].includes(share.scope)) return 'unknown-scope'
+/**
+ * A share the owner may give - a known scope with a target; the domain scope names the owner's own domain, a role one
+ * of the domain's roles (`roleIds`, the ones it inherits included).
+ */
+export function shareRefusal(share: CardShareRow, owner: { domainId: string; departmentsAvailable: boolean; roleIds?: readonly string[] }): string | undefined {
+  if (!['USER', 'DEPARTMENT', 'ROLE', 'DOMAIN'].includes(share.scope)) return 'unknown-scope'
   if (!share.targetId) return 'no-target'
   if (share.scope === 'DOMAIN' && share.targetId !== owner.domainId) return 'another-domain'
   if (share.scope === 'DEPARTMENT' && !owner.departmentsAvailable) return 'no-departments'
+  if (share.scope === 'ROLE' && !(owner.roleIds ?? []).includes(share.targetId)) return 'unknown-role'
   return undefined
 }

package/server/service/card/card-definition.ts

@@ -16,7 +16,9 @@ export const CARD_SCHEMA_VERSION = 1
 export const VIEW_KINDS = ['number', 'table', 'bar', 'line'] as const
 export type ViewKind = (typeof VIEW_KINDS)[number]
 
-export const MATCH_OPS = ['eq', 'ne', 'gt', 'gte', 'lt', 'lte'] as const
+export const MATCH_OPS = ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'not_in'] as const
+/** The operators whose value is a list - one of these values, none of them. */
+export const LIST_OPS = ['in', 'not_in'] as const
 export type MatchOp = (typeof MATCH_OPS)[number]
 
 /** The rows a table shows, and the points a chart draws, at most (ADR-0160 decision 4). */
@@ -38,7 +40,8 @@ export interface CardSourceRef {
 export interface CardMatch {
   column: string
   op: MatchOp
-  value: string | number | boolean
+  /** A list for `in` and `not_in` (status not_in [APPROVED, REJECTED, WITHDRAWN]); one value otherwise. */
+  value: string | number | boolean | (string | number)[]
 }
 
 export interface CardRows {
@@ -82,6 +85,10 @@ export interface SourceCondition {
   description?: string
   /** A detail read's argument its query cannot run without. */
   required?: boolean
+  /** A string condition that holds a month as YYYY-MM - it takes a relative month (this-month, -5m). */
+  format?: 'month'
+  /** It takes several values at once - a list read's statuses (`status: [..]`, `statusNot: [..]`). */
+  many?: boolean
 }
 
 /** What a card may read from one declaration - the same whichever kind of read it is. */
@@ -96,6 +103,8 @@ export interface CardSource {
   target?: ReadTarget
   detail?: DetailRead
   list?: DetailList
+  /** The rows are the viewer's own, whoever looks (내 지출결의, 나의 전략 업무) - ReadTarget.mine · DetailRead.mine. */
+  mine?: boolean
 }
 
 /** The source a reference names - or why there is none. */
@@ -117,10 +126,11 @@ export function sourceOf(
         query: target.query,
         columns: target.columns,
         conditions: [
-          ...target.criteria.map(one => ({ name: one.name, type: one.type, values: one.values, description: one.description })),
+          ...target.criteria.map(one => ({ name: one.name, type: one.type, values: one.values, description: one.description, ...(one.format ? { format: one.format } : {}), ...(one.many ? { many: true } : {}) })),
           ...(target.search ? [{ name: 'text', type: 'string', description: target.search.description }] : [])
         ],
-        target
+        target,
+        ...(target.mine ? { mine: true } : {})
       }
     }
   }
@@ -139,20 +149,32 @@ export function sourceOf(
       description: list.description ?? detail.description,
       query: detail.query,
       columns: list.columns,
-      conditions: (detail.args ?? []).map(one => ({ name: one.name, type: one.type, values: one.values, description: one.description, required: !!one.required })),
+      conditions: (detail.args ?? []).map(one => ({ name: one.name, type: one.type, values: one.values, description: one.description, required: !!one.required, ...(one.format ? { format: one.format } : {}) })),
       detail,
-      list
+      list,
+      ...(detail.mine ? { mine: true } : {})
     }
   }
 }
 
 /* ── Relative dates (ADR-0160 decision 3) ─────────────────────────────────────────────────────────────────── */
 
-const RELATIVE_DATE = /^(today|(this|last|next)-(week|month|quarter|year)-(start|end)|[+-]?\d{1,4}d)$/
-const RELATIVE_PERIOD = /^(this|last|next)-(year|month)$/
+/*
+ * The words of a period that stays current - the only ones a card keeps:
+ *   a day      today · -30d · this-month-start · last-year-end · -5m-start (the first day of five months ago)
+ *   a year or a month as an integer   this-year · last-month · -5m
+ *   a month as YYYY-MM                this-month · last-month · -5m · this-year-start (its January) · this-year-end
+ * "The last six months" is from -5m-start to this-month-end (or a YYYY-MM range from -5m to this-month).
+ */
+const RELATIVE_DATE = /^(today|(this|last|next)-(week|month|quarter|year)-(start|end)|[+-]?\d{1,4}d|-\d{1,2}m-(start|end))$/
+const RELATIVE_PERIOD = /^((this|last|next)-(year|month)|-\d{1,2}m)$/
+const RELATIVE_MONTH = /^((this|last|next)-month|-\d{1,2}m|(this|last|next)-year-(start|end))$/
+/** A value that looks meant as a relative one - checked against the words above, never taken for a literal. */
+const LOOKS_RELATIVE = /^((this|last|next)-|today$|-\d)/
 
 export const isRelativeDate = (value: unknown) => typeof value === 'string' && RELATIVE_DATE.test(value)
 export const isRelativePeriod = (value: unknown) => typeof value === 'string' && RELATIVE_PERIOD.test(value)
+export const isRelativeMonth = (value: unknown) => typeof value === 'string' && RELATIVE_MONTH.test(value)
 
 const pad = (n: number) => String(n).padStart(2, '0')
 const ymd = (date: Date) => `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`
@@ -173,6 +195,8 @@ export function resolveRelativeDate(value: string, today: string): string {
   if (value === 'today') return today
   const days = /^([+-]?\d{1,4})d$/.exec(value)
   if (days) return ymd(utc(y, m - 1, d + Number(days[1])))
+  const monthsAgo = /^-(\d{1,2})m-(start|end)$/.exec(value)
+  if (monthsAgo) return ymd(monthsAgo[2] === 'start' ? utc(y, m - 1 - Number(monthsAgo[1]), 1) : utc(y, m - Number(monthsAgo[1]), 0))
   const [, which, unit, edge] = /^(this|last|next)-(week|month|quarter|year)-(start|end)$/.exec(value)!
   const step = which === 'last' ? -1 : which === 'next' ? 1 : 0
   if (unit === 'week') {
@@ -188,24 +212,39 @@ export function resolveRelativeDate(value: string, today: string): string {
   return ymd(edge === 'start' ? utc(y + step, 0, 1) : utc(y + step, 11, 31))
 }
 
+/** How many months a relative month moves from this one - `last-month` -1, `-5m` -5. */
+const monthStep = (value: string) => (/^-(\d{1,2})m$/.test(value) ? -Number(value.slice(1, -1)) : value.startsWith('last') ? -1 : value.startsWith('next') ? 1 : 0)
+
+/** A relative month as YYYY-MM, from `today` - `this-year-start` is this year's January. */
+export function resolveRelativeMonth(value: string, today: string): string {
+  const [y, m] = today.split('-').map(Number)
+  const year = /^(this|last|next)-year-(start|end)$/.exec(value)
+  if (year) return `${y + (year[1] === 'last' ? -1 : year[1] === 'next' ? 1 : 0)}-${year[2] === 'start' ? '01' : '12'}`
+  const month = utc(y, m - 1 + monthStep(value), 1)
+  return `${month.getUTCFullYear()}-${pad(month.getUTCMonth() + 1)}`
+}
+
 /**
- * The relative values of a definition's conditions, as of `today`. A year and a month are read from one month: with a
- * month token in the same conditions, `this-year` is that month's year - January's `last-month` with `this-year` is
- * last December, never this year's December.
+ * The relative values of a definition's conditions, as of `today` - each by what its condition holds (`conditions`):
+ * a month as YYYY-MM, a day, an integer year or month. A year and a month are read from one month: with a month token
+ * in the same conditions, `this-year` is that month's year - January's `last-month` with `this-year` is last December,
+ * never this year's December.
  */
-export function resolveWhere(where: Record<string, unknown> | undefined, today: string): Record<string, unknown> {
+export function resolveWhere(where: Record<string, unknown> | undefined, today: string, conditions: readonly SourceCondition[] = []): Record<string, unknown> {
   const given = where ?? {}
+  const formats = new Map(conditions.map(one => [one.name, one.format]))
   const [y, m] = today.split('-').map(Number)
-  const monthToken = Object.values(given).find(value => typeof value === 'string' && /^(this|last|next)-month$/.test(value)) as string | undefined
-  const base = monthToken ? utc(y, m - 1 + (monthToken.startsWith('last') ? -1 : monthToken.startsWith('next') ? 1 : 0), 1) : utc(y, m - 1, 1)
+  const monthToken = Object.entries(given).find(([name, value]) => formats.get(name) !== 'month' && typeof value === 'string' && /^((this|last|next)-month|-\d{1,2}m)$/.test(value))?.[1] as string | undefined
+  const base = monthToken ? utc(y, m - 1 + monthStep(monthToken), 1) : utc(y, m - 1, 1)
   const baseYear = base.getUTCFullYear()
   const out: Record<string, unknown> = {}
   for (const [name, value] of Object.entries(given)) {
-    if (isRelativeDate(value)) out[name] = resolveRelativeDate(value as string, today)
+    if (formats.get(name) === 'month' && isRelativeMonth(value)) out[name] = resolveRelativeMonth(value as string, today)
+    else if (isRelativeDate(value)) out[name] = resolveRelativeDate(value as string, today)
     else if (isRelativePeriod(value)) {
       const [which, unit] = (value as string).split('-')
       const step = which === 'last' ? -1 : which === 'next' ? 1 : 0
-      out[name] = unit === 'month' ? base.getUTCMonth() + 1 : baseYear + step
+      out[name] = unit === 'year' ? baseYear + step : base.getUTCMonth() + 1
     } else out[name] = value
   }
   return out
@@ -245,7 +284,11 @@ export function checkDefinition(definition: CardDefinition | undefined, source:
       issues.push({ code: 'unknown-condition', params: { name, conditions: [...conditions.keys()], ...(column ? { isColumn: true, use: `rows.match: [{ column: '${name}', op: 'eq', value: ${JSON.stringify(value)} }]` } : {}) } })
       continue
     }
-    if (typeof value === 'string' && /^(this|last|next)-/.test(value) && !isRelativeDate(value) && !isRelativePeriod(value)) issues.push({ code: 'unknown-relative-value', params: { name, value } })
+    if (condition?.format === 'month') {
+      if (typeof value === 'string' && LOOKS_RELATIVE.test(value) && !isRelativeMonth(value)) issues.push({ code: 'relative-value-unfit', params: { name, value, takes: 'a month as YYYY-MM, or this-month, last-month, -5m, this-year-start, this-year-end' } })
+      continue
+    }
+    if (typeof value === 'string' && LOOKS_RELATIVE.test(value) && !isRelativeDate(value) && !isRelativePeriod(value)) issues.push({ code: 'unknown-relative-value', params: { name, value } })
     if (isRelativePeriod(value) && condition?.type !== 'integer') issues.push({ code: 'relative-period-on-non-integer', params: { name, value } })
     if (isRelativeDate(value) && condition?.type !== 'date') issues.push({ code: 'relative-date-on-non-date', params: { name, value } })
   }
@@ -259,10 +302,41 @@ export function checkDefinition(definition: CardDefinition | undefined, source:
   const columns = new Map(source.columns.map(one => [one.name, one]))
   const columnNames = [...columns.keys()]
   const rows = definition.rows ?? {}
+  const scalar = (value: unknown) => typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
   for (const match of rows.match ?? []) {
     if (!columns.has(match?.column)) issues.push({ code: 'unknown-column', params: { where: 'match', column: match?.column ?? null, columns: columnNames } })
     if (!known(MATCH_OPS, match?.op)) issues.push({ code: 'unknown-operator', params: { op: match?.op ?? null, ops: MATCH_OPS } })
-    if (match?.value === undefined || match?.value === null || typeof match.value === 'object') issues.push({ code: 'match-without-value', params: { column: match?.column ?? null } })
+    else if (known(LIST_OPS, match.op)) {
+      if (!Array.isArray(match.value) || !match.value.length || !match.value.every(scalar)) issues.push({ code: 'match-without-values', params: { column: match.column, op: match.op } })
+    } else if (match?.value === undefined || match?.value === null || !scalar(match.value)) issues.push({ code: 'match-without-value', params: { column: match?.column ?? null } })
+    /*
+     * A relative value is read on a date column only - on another it is the literal text 「this-month」, which no row
+     * holds: 「이번 달 지출결의 합계」 matched month eq this-month and drew 0 (2026-10-25). A period is the source's
+     * condition (a YYYY-MM one takes this-month).
+     */
+    const column = columns.get(match?.column)
+    const relative = (Array.isArray(match?.value) ? match.value : [match?.value]).filter(one => typeof one === 'string' && LOOKS_RELATIVE.test(one))
+    if (column && relative.length) {
+      if (column.type !== 'date') issues.push({ code: 'relative-value-on-non-date-column', params: { column: column.name, value: relative[0], periodConditions: source.conditions.filter(one => one.type === 'date' || one.format === 'month' || (one.type === 'integer' && /year|month/i.test(one.name))).map(one => one.name) } })
+      else if (relative.some(one => !isRelativeDate(one))) issues.push({ code: 'unknown-relative-value', params: { name: column.name, value: relative.find(one => !isRelativeDate(one)) } })
+    }
+  }
+  /*
+   * Conditions that no row can meet - two `eq` of one column (status 작성중 AND 상신), or an `eq` outside its own `in`.
+   * Every match must hold, so these draw nothing, or a number of nothing that looks true (2026-10-25).
+   */
+  const equals = new Map<string, Set<string>>()
+  for (const match of rows.match ?? []) {
+    if (!match || typeof match.column !== 'string') continue
+    const values = match.op === 'eq' && scalar(match.value) ? [String(match.value)] : match.op === 'in' && Array.isArray(match.value) ? match.value.map(String) : undefined
+    if (!values) continue
+    const before = equals.get(match.column)
+    const kept = before ? values.filter(one => before.has(one)) : values
+    if (before && !kept.length) {
+      issues.push({ code: 'match-never-true', params: { column: match.column, use: `one match of ${match.column} with op in and every value it may hold` } })
+      continue
+    }
+    equals.set(match.column, new Set(kept))
   }
   if (rows.groupBy !== undefined) {
     const by = columns.get(rows.groupBy)
@@ -296,3 +370,93 @@ export function checkDefinition(definition: CardDefinition | undefined, source:
   if (view.unit !== undefined && (typeof view.unit !== 'string' || view.unit.length > 20)) issues.push({ code: 'unit-too-long' })
   return issues
 }
+
+/* ── What the card says it shows, against what it reads ───────────────────────────────────────────────────── */
+
+export type PeriodUnit = 'day' | 'week' | 'month' | 'months' | 'year'
+
+/*
+ * The periods a card's name or line may say, in the languages the module ships the most - a name the dashboard shows
+ * every day. 「이번 달 합계」 with no condition of the month summed all time (2026-10-25).
+ */
+const NAMED_PERIODS: [PeriodUnit, RegExp][] = [
+  ['months', /(최근|지난)\s*\d+\s*개월|\d+\s*개월\s*(간|동안)|\b(last|past)\s+\d+\s+months?\b|過去\s*\d+\s*(ヶ|か|カ)月|近\s*\d+\s*个月/i],
+  ['month', /이번\s*달|이달|금월|당월|지난\s*달|저번\s*달|전월|다음\s*달|\b(this|last|next)\s+month\b|今月|先月|本月|上个?月/i],
+  ['year', /올해|금년|당해|작년|지난\s*해|전년도|내년|\b(this|last|next)\s+year\b|今年|昨年|去年/i],
+  ['week', /이번\s*주|금주|지난\s*주|저번\s*주|다음\s*주|\b(this|last|next)\s+week\b|今週|先週|本周|上周/i],
+  ['day', /오늘|금일|\btoday\b|今日|今天/i]
+]
+
+/** The periods a text says - none for a text without one. */
+export function periodsNamed(text: string | undefined): PeriodUnit[] {
+  const given = String(text ?? '')
+  return NAMED_PERIODS.filter(([, words]) => words.test(given)).map(([unit]) => unit)
+}
+
+/** The units a relative value reads - `this-month-start` a month, `-5m` months back, `-30d` days. */
+function unitsOf(value: unknown): PeriodUnit[] {
+  if (typeof value !== 'string') return []
+  if (/^-\d{1,2}m(-(start|end))?$/.test(value)) return ['months']
+  if (/^today$|^[+-]?\d{1,4}d$/.test(value)) return /^[+-]?([7-9]|1[0-4])d$/.test(value) ? ['day', 'week'] : ['day']
+  const unit = /^(this|last|next)-(week|month|quarter|year)/.exec(value)?.[2]
+  return unit === 'quarter' ? ['months'] : unit ? [unit as PeriodUnit] : []
+}
+
+const FIXED_DAY = /^\d{4}(-\d{2}(-\d{2})?)?$/
+/** A bound held to one day, month or year - `2026-10-01`, `2026-10`, or an integer year or month (`year: 2026, month: 10`). */
+const isFixed = (value: unknown) => typeof value === 'number' || (typeof value === 'string' && FIXED_DAY.test(value))
+
+/** The viewer as the definition may name them by mistake - their user id, name and e-mail. */
+export interface ViewerNames {
+  id?: string
+  name?: string
+  email?: string
+}
+
+/**
+ * Whether a card means what its name says, and reads as whoever looks at it. Issues, never repairs:
+ *  - a period in the name or line (이번 달, 최근 6개월) with no condition of that period - it would sum all time;
+ *  - a period said relatively but held to fixed days - it would stop being "this month" next month;
+ *  - a filter on the viewer's own name or id: a read of the viewer's own rows needs none (it is theirs whoever looks),
+ *    and another read filtered by one person shows that person to everyone the card is shared with - the viewer's own
+ *    read (`mine`) is the source instead.
+ * `mineSources` are the reads of one's own rows the model may use instead (cardSources).
+ */
+export function checkCardIntent(
+  card: { name?: string; description?: string; definition: CardDefinition },
+  source: CardSource,
+  viewer: ViewerNames = {},
+  mineSources: string[] = []
+): CardIssue[] {
+  const issues: CardIssue[] = []
+  const { definition } = card
+  const where = definition.source?.where ?? {}
+  const matches = definition.rows?.match ?? []
+  const dateColumns = new Set(source.columns.filter(one => one.type === 'date').map(one => one.name))
+  const periodConditions = new Set(source.conditions.filter(one => one.type === 'date' || one.format === 'month' || (one.type === 'integer' && /year|month/i.test(one.name))).map(one => one.name))
+
+  /* The values that bound a period - a period condition's, a date column's match. */
+  const bounds = [
+    ...Object.entries(where).filter(([name]) => periodConditions.has(name)).map(([, value]) => value),
+    ...matches.filter(one => dateColumns.has(one?.column)).map(one => one.value)
+  ]
+  const named = [...new Set([...periodsNamed(card.name), ...periodsNamed(card.description)])]
+  if (named.length) {
+    if (!bounds.length) issues.push({ code: 'period-without-condition', params: { said: named, conditions: [...periodConditions], dateColumns: [...dateColumns] } })
+    else if (bounds.some(isFixed)) issues.push({ code: 'period-held-to-fixed-days', params: { said: named, given: bounds.filter(isFixed) } })
+    else {
+      const read = new Set(bounds.flatMap(unitsOf))
+      const missing = named.filter(unit => !read.has(unit))
+      if (read.size && missing.length) issues.push({ code: 'period-unlike-condition', params: { said: missing, given: bounds } })
+    }
+  }
+
+  const own = [viewer.id, viewer.name, viewer.email].filter((one): one is string => !!one && one.trim().length > 1).map(one => one.trim().toLowerCase())
+  const isOwn = (value: unknown) => (Array.isArray(value) ? value : [value]).some(one => (typeof one === 'string' || typeof one === 'number') && own.includes(String(one).trim().toLowerCase()))
+  const onViewer = [...Object.entries(where).filter(([, value]) => isOwn(value)).map(([name]) => name), ...matches.filter(one => isOwn(one?.value)).map(one => one.column)]
+  if (onViewer.length) {
+    if (source.mine) issues.push({ code: 'viewer-filter-on-own-read', params: { filters: onViewer } })
+    else if (mineSources.length) issues.push({ code: 'viewer-filter-use-own-read', params: { filters: onViewer, mine: mineSources } })
+  }
+  return issues
+}