Skip to content

docs: document timestamp column units (epoch ms) in ARCHITECTURE.md and fresh-install schema - #458

Open
G0-0000 wants to merge 3 commits into
cortexkit:masterfrom
G0-0000:docs/timestamp-units-verified
Open

G0-0000 wants to merge 3 commits into
cortexkit:masterfrom
G0-0000:docs/timestamp-units-verified

Conversation

@G0-0000

@G0-0000 G0-0000 commented Sep 16, 2026

Copy link
Copy Markdown

Follow-up to #457, reshaped per maintainer feedback (magic-alfonso).

Changes

ARCHITECTURE.md — added a ### Timestamp Columns table in the storage section listing each created_at/updated_at column with its unit (epoch ms) and the writer that stamps it. Every row was verified against its writer; columns with mixed writers (memories host/Rust-mirror) or non-TypeScript writers (workspaces, dashboard Rust) are called out explicitly rather than blanket-asserted.

packages/plugin/src/features/magic-context/storage-db.ts — adds -- epoch ms (Date.now()) comments to created_at columns in the fresh-install schema only (no migration DDL touched — shipped migrations stay append-only). Only columns verified to be stamped by Date.now() get the comment; memories/workspaces are deliberately omitted.

No behavior change. Not touching migrations.ts per the maintainer's "applied migrations are history" note.


View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.


Summary by cubic

Documents the audited timestamp columns as epoch milliseconds in ARCHITECTURE.md and annotates verified fresh-install schema columns with their Date.now() units. Clarifies timestamp handling without changing runtime behavior or migration history.

  • The architecture table lists each column's writer and flags caller-supplied overrides (row.createdAt, candidate.createdAt, input.now, refreshedAt), clone-preserved timestamps, and mixed (memories) or Rust (workspaces) writers.
  • Schema comments appear only where Date.now() is the actual writer.
  • Shipped migrations are unchanged, so existing databases need no migration step.

Written for commit 8d76de6. Summary will update on new commits.

Review in cubic

Greptile Summary

Documents the units and provenance of audited timestamp columns without changing runtime behavior or migration history.

  • Adds an architecture table covering epoch-millisecond timestamp writers, caller overrides, clone preservation, schema defaults, and mixed TypeScript/Rust writers.
  • Annotates verified fresh-install schema columns with timestamp-unit comments.
  • Clarifies that primer answer refreshes may supply refreshedAt.

Confidence Score: 5/5

The PR appears safe to merge because it only clarifies timestamp documentation and schema comments, with no outstanding correctness or repository-rule issues.

The prior timestamp-provenance concern was addressed and its thread is resolved; the subsequent refreshedAt clarification accurately documents the remaining caller-supplied path.

Important Files Changed
Filename Overview
ARCHITECTURE.md Adds an audited timestamp-unit and writer-provenance reference, including explicit override and preservation paths.
packages/plugin/src/features/magic-context/storage-db.ts Adds comments to fresh-install schema declarations without altering SQL semantics or migration history.

Reviews (3): Last reviewed commit: "docs: note refreshedAt override on prime..." | Re-trigger Greptile

Comment thread ARCHITECTURE.md Outdated

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 2 files

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

Comment thread packages/plugin/src/features/magic-context/storage-db.ts Outdated
…ion)

Address Greptile/cubic review:
- ARCHITECTURE.md: flag caller-supplied timestamp paths in the table
  (row.createdAt for compartment_chunk_embeddings, candidate.createdAt
  for primer_candidates, input.now for primers); add Notes covering the
  session-clone path (copySessionStateForClone preserves created_at
  verbatim) and the NOT NULL DEFAULT 0 backstop on ledger columns.
- storage-db.ts: source_contents.created_at comment now reads
  "epoch ms; Date.now() on source writes, preserved on session clones".

Docs/comments only; no behavior or migration changes.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 2 files (changes from recent commits).

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

Comment thread ARCHITECTURE.md Outdated
updatePrimerAnswer() honors caller-supplied refreshedAt for
primers.updated_at (default Date.now()); the table row previously
listed only input.now. Docs only.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant