Skip to content

Add v2 typed materialization API - #31

Merged
ggoodman merged 61 commits into
mainfrom
codex/v2-typed-projection-api
Jul 27, 2026
Merged

Add v2 typed materialization API#31
ggoodman merged 61 commits into
mainfrom
codex/v2-typed-projection-api

Conversation

@ggoodman

@ggoodman ggoodman commented Jun 17, 2026

Copy link
Copy Markdown
Contributor

Summary

This is a breaking v2 ledger construction rewrite, not a bolt-on projection module.

  • Replaces the old defineLedgerModel / registerLedgerModel / bindLedgerModel path with defineLedgerShape(...), defineMaterializationSchema(...), defineMaterializationHistory(...), defineMaterializations(...), withMaterializations(...), and .register(...).
  • Splits the lifecycle into separate surfaces: ledger shape, current materialization schema DDL, materialization migration history, materialization contracts, and executable registration.
  • Makes materialization DDL object-shaped: each table key owns a table-local builder function, and optional relations runs as a second phase over inferred tables.
  • Adds defineMaterializationHistory(currentSchema, ...), a typed migration DSL that records ordered create-table, add-column, create-index, create-unique-index, add-foreign-key, and data migration operations as data.
  • Adds s.data(description, async ({ db }) => ...) migration steps with a Sledge-owned typed migration database facade for selectFrom, insertInto, updateTable, and deleteFrom; no raw SQL or storage handle is exposed.
  • Replaces the previous versioned-DDL array and from / to migration callback metadata with a single canonical current schema plus explicit migration history.
  • Defines indexers and queries as plain-object contracts in defineMaterializations(...); implementations are supplied later as matching plain maps in .register(...).
  • Removes the rejected p.indexer(...) / p.query(...) handle pattern and the prior .withProjections(...) shape method.
  • Keeps semantic event refs first-class with t.eventRef("event.name"); handlers write event.ref rather than touching the internal events table.
  • Validates materialization event refs and indexer source events against the ledger shape at both the type boundary and runtime boundary where possible.
  • Keeps user indexer/query/migration callbacks behind sledge-owned insert/upsert/select/update/delete facades instead of raw SQL handles.
  • Rejects non-serializable JSON projection values at the facade boundary before storage adapters receive bind parameters.
  • Moves the adapter contract harnesses onto the v2 materialization/indexer/query API; the remaining raw SQL there is temporary table DDL until materialization migrations execute.
  • Changes storage adapters to accept a registered model instead of boundModel.

This is still not a Postgres driver and does not implement materialization migration execution. It is the v2 public API slice that makes typed materialization schema, ordered migration history, and facade-only materialization access the center of ledger construction before runtime/storage execution is added.

Diff Shape

  • Latest review-feedback commit: 3 files changed, 246 insertions(+), 1 deletion(-).
  • Previous data-migration commit: 4 files changed, 275 insertions(+), 36 deletions(-).
  • Previous migration-history commit: 5 files changed, 869 insertions(+), 250 deletions(-).
  • Full PR diff: 15 files changed, 5384 insertions(+), 866 deletions(-).
  • The old construction/binding surface and duplicate raw contract implementations have been culled; the added bulk is the DDL/access DSL, typed migration history metadata, the rewritten contract harness, and type/runtime tests.

Validation

  • node --run lint passed.
  • node --run typecheck passed.
  • node --run build passed.
  • node --test src/ledger/ledger-projections.test.ts src/ledger/projections.test.ts src/ledger/turso-ledger.contract.test.ts passed: 21 tests.
  • npm pack --dry-run passed after build: 43 files. I used a temp npm cache because the default ~/.npm cache has root-owned files.
  • node --run test attempted locally: 28 tests passed, including Turso contract and materialization/projection coverage; the remaining 47 failures are the known local better-sqlite3 native binding lookup (Could not locate the bindings file). I did not rebuild or install native modules locally.
  • GitHub Verify (Node 24) passed on head 474719c2353ddfa6eb0c93c77d501b585f149c02.
  • Unresolved review threads: 0.

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

@ggoodman

Copy link
Copy Markdown
Contributor Author

@codex ptal

@ggoodman ggoodman changed the title Add typed projection schema API Add v2 typed projection access API Jun 18, 2026
@ggoodman
ggoodman marked this pull request as draft June 18, 2026 01:26
@ggoodman
ggoodman marked this pull request as ready for review June 19, 2026 01:43

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e7a4e097dc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/ledger/database-ledger-engine.ts
Comment thread src/ledger/ledger.ts Outdated
Comment thread src/ledger/projections.ts
@ggoodman ggoodman changed the title Add v2 typed projection access API Add v2 typed materialization API Jun 19, 2026

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 53bb445a62

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/ledger/projection-access.ts Outdated
@ggoodman

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 474719c235

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/ledger/better-sqlite3-ledger.ts
Comment thread src/ledger/ledger.ts
Comment thread src/ledger/ledger.ts
Comment thread src/ledger/projection-access.ts
@ggoodman

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b797adcfea

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/ledger/ledger.ts
Comment thread src/ledger/ledger.ts Outdated
Comment thread src/ledger/ledger.ts
Comment thread src/ledger/projection-access.ts Outdated
Comment thread src/ledger/ledger.ts
@ggoodman

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 24bfde0321

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/ledger/ledger.ts Outdated
@ggoodman
ggoodman force-pushed the codex/v2-typed-projection-api branch from 5f9fe1a to aede8ef Compare June 21, 2026 01:58
@ggoodman
ggoodman force-pushed the codex/v2-typed-projection-api branch from 918ebe9 to 13d1579 Compare June 21, 2026 11:51
@ggoodman

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: db702db22b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/ledger/database-ledger-engine.ts Outdated
Comment thread README.md Outdated
Comment thread src/ledger/database-ledger-engine.ts Outdated
Comment thread README.md Outdated
Comment thread src/ledger/database-ledger-engine.ts Outdated
@ggoodman

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3d0aceb335

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/ledger/database-ledger-engine.ts
Comment thread src/ledger/projection-access.ts Outdated
Comment thread src/ledger/projection-access.ts
Comment thread src/ledger/ledger.ts Outdated
Comment thread src/ledger/projection-access.ts Outdated
@ggoodman

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: cebd7085d7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@ggoodman

Copy link
Copy Markdown
Contributor Author

@codex ptal

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 358367cdcd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/ledger/database-ledger-engine.ts Outdated
Comment thread src/ledger/ledger.ts Outdated
Comment thread src/ledger/ledger.ts Outdated
Comment thread src/ledger/ledger.ts
Comment thread src/ledger/database-ledger-engine.ts Outdated
Comment thread src/ledger/projection-access.ts
@ggoodman

Copy link
Copy Markdown
Contributor Author

@codex PTAL

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: 82dc13f49f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@ggoodman
ggoodman merged commit df058c5 into main Jul 27, 2026
1 check passed
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