Premain

.release-please-manifest.premain.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.2.0-rc"
+  ".": "1.3.0-rc.1"
 }

CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [1.3.0-rc.1](https://github.com/theory-cloud/TableTheory/compare/v1.3.0-rc...v1.3.0-rc.1) (2026-01-23)
+
+
+### Features
+
+* FaceTheory ISR support (FT-T0..FT-T4) ([66eb65a](https://github.com/theory-cloud/TableTheory/commit/66eb65af9b253946c53f4f88af9dc10668e6d5bd))
+* FT-T1 lease helper (Go) ([bb6860a](https://github.com/theory-cloud/TableTheory/commit/bb6860a46380f1227a067dd87ea9fd0d8c4f4f34))
+* FT-T1 lease helper (Py) ([71b1c01](https://github.com/theory-cloud/TableTheory/commit/71b1c01ca9d8347e8443627c023d698f4ce4d34b))
+* FT-T1 lease helper (TS) ([b04dbb1](https://github.com/theory-cloud/TableTheory/commit/b04dbb17cc72b25d0ba328680170b64fcc37efc6))
+* **mocks:** add transaction builder mock ([ea39672](https://github.com/theory-cloud/TableTheory/commit/ea39672edffd22bf24b1471e244c14b79f06211d))
+* **mocks:** add transaction builder mock ([16ab5a5](https://github.com/theory-cloud/TableTheory/commit/16ab5a5d7b22d1087973f96a5c69b2c3a3796c3e))
+
+
+### Bug Fixes
+
+* address security/quality findings ([3b56fb4](https://github.com/theory-cloud/TableTheory/commit/3b56fb4986d2a0e93ced5c682caa2fd401a62087))
+* address security/quality findings ([f7adaf7](https://github.com/theory-cloud/TableTheory/commit/f7adaf79d1e7248d3b2654f5c82b33f79cc6e4ac))
+* **ci:** make release assets immutable ([1ef4aca](https://github.com/theory-cloud/TableTheory/commit/1ef4aca7bbd6ef6fffe9a86b9f33b1c0c28e1e97))
+* **ci:** make release assets immutable ([e9ad219](https://github.com/theory-cloud/TableTheory/commit/e9ad219f7d806e8faff7422c45ea2b1f066e3904))
+* **ci:** retry git fetch in branch-version-sync ([1b4d855](https://github.com/theory-cloud/TableTheory/commit/1b4d8557fe66c5c333846469369d9e5285cc1232))
+* improved transaction handling ([30a5d7a](https://github.com/theory-cloud/TableTheory/commit/30a5d7acc371cbcbd38bee1d240e5eab24d49882))
+* **mocks:** satisfy lint gates ([a9cd117](https://github.com/theory-cloud/TableTheory/commit/a9cd1170fc200489369b76f098635321ed3d81c0))
+* **premain:** restore prerelease version alignment ([9b07cdb](https://github.com/theory-cloud/TableTheory/commit/9b07cdb7df5e69be8012374f742d89252ffde942))
+* **security:** harden API key hashing ([2c47b6c](https://github.com/theory-cloud/TableTheory/commit/2c47b6c7dac1084b66448f81dc3d49ce4e4114e0))
+
 ## [1.2.0](https://github.com/theory-cloud/TableTheory/compare/v1.1.5...v1.2.0) (2026-01-22)
 
 

docs/README.md

@@ -20,6 +20,10 @@
 
 - [API Reference (Go)](./api-reference.md) – Go SDK public API (DB, Query, Transactions)
 - [Core Patterns (Go)](./core-patterns.md) – Go SDK canonical usage patterns (Lambda, Batch, Streams)
+- [FaceTheory ISR Cache Schema](./facetheory/isr-cache-schema.md) – Recommended cache metadata + regeneration lease item shapes
+- [FaceTheory ISR Transaction Recipes](./facetheory/isr-transaction-recipes.md) – Correctness-first patterns for publishing metadata under lease
+- [FaceTheory TTL Cache Patterns](./facetheory/ttl-cache-patterns.md) – Freshness vs expiry, TTL lag, and operational guidance for ISR tables
+- [FaceTheory ISR Idempotency Patterns](./facetheory/isr-idempotency.md) – Request-id driven regeneration guidance and replay safety
 - [Development Guidelines](./development-guidelines.md) – Repo-wide coding standards (Go + TS + Python)
 - [Testing Guide](./testing-guide.md) – Repo-wide testing strategy (Go + TS + Python)
 - [Troubleshooting (Go)](./troubleshooting.md) – Go SDK troubleshooting (TypeScript/Python have their own)

docs/development/planning/README.md

@@ -13,6 +13,7 @@ Start here:
 - `docs/development/planning/theorydb-10of10-rubric.md` (the definition of “good”; versioned)
 - `docs/development/planning/theorydb-10of10-roadmap.md` (milestones mapped to rubric IDs)
 - `docs/development/planning/theorydb-multilang-roadmap.md` (multi-language expansion plan; TypeScript first)
+- `docs/development/planning/theorydb-facetheory-support-roadmap.md` (FaceTheory enablement: ISR locks + cache metadata)
 - `docs/development/planning/theorydb-spec-dms-v0.1.md` (language-agnostic schema + semantics contract, draft)
 - `docs/development/planning/theorydb-go-ts-parity-matrix.md` (feature parity tiers for TypeScript)
 - `docs/development/planning/theorydb-multilang-feature-parity-matrix.md` (feature parity across Go/TS/Py)

docs/development/planning/theorydb-facetheory-support-roadmap.md

@@ -0,0 +1,113 @@
+# TableTheory: FaceTheory Enablement Roadmap (ISR Locks + Cache Metadata)
+
+This roadmap captures what TableTheory should provide so **FaceTheory** can implement **SSG + ISR** on AWS with
+correctness-first semantics and without per-app “glue code” re-implementations.
+
+Source document: `FaceTheory/docs/WISHLIST.md` (TableTheory wishlist section).
+
+## Baseline (current)
+
+As of TableTheory `v1.1.5`:
+
+- TableTheory has strong DynamoDB primitives (conditional writes, transactions) and a contract-test posture.
+- TTL encoding is covered by the contract suite (`ttl` as epoch seconds) and is safe to build cache tables around.
+- Documentation already contains **idempotency/locking patterns** (see `docs/cdk/README.md`), but these patterns are not
+  yet packaged as small, canonical, multi-language helpers.
+
+## Goals
+
+- Provide a **canonical** and **portable** implementation for ISR regeneration locks (lease/lock).
+- Provide safe “transaction recipes” for cache metadata updates (pointer swap, freshness, etag) that apps can copy or call.
+- Provide TTL-first cache schema guidance so teams don’t invent incompatible models.
+- Keep TableTheory’s supply-chain posture: **GitHub releases only** for TS/Py assets; no registry tokens.
+
+## Non-goals (initially)
+
+- A full “FaceTheory cache framework” inside TableTheory (FaceTheory owns ISR policies and rendering orchestration).
+- Storing full HTML in DynamoDB (FaceTheory stores bodies in S3; DynamoDB is metadata + locks only).
+
+## Milestones
+
+### FT-T0 — ISR cache schema guidance (docs + recommended model shapes)
+
+**Goal:** standardize the DynamoDB model shape used for ISR cache metadata and regeneration locks.
+
+**Acceptance criteria**
+- A doc exists describing recommended roles for a “FaceTheory cache metadata” table:
+  - key design (cache key partitioning, tenant partitioning guidance)
+  - metadata attributes (S3 object key pointer, `generated_at`, `revalidate_seconds`, `etag`, etc)
+  - TTL strategy and pitfalls (TTL lag, safety buffer)
+- The doc includes at least one runnable model definition per language (Go struct, TS type, Py dataclass/pydantic) showing:
+  - canonical tags/roles (`pk`, optional `sk`, `ttl`)
+  - attribute naming conventions
+- Guidance explicitly calls out where transactions are required vs optional.
+
+---
+
+### FT-T1 — Lease/lock helper (canonical, multi-language)
+
+**Goal:** ship a small helper for distributed regeneration locks with safe defaults and predictable failure modes.
+
+**Wishlist mapping:** “Lease/lock helper patterns” (FaceTheory P0).
+
+**Acceptance criteria**
+- Go/TS/Py each expose a small, focused lease API (names TBD) that supports:
+  - acquire via conditional write with lease expiry
+  - optional refresh/extend
+  - best-effort release
+- The helper is safe-by-default:
+  - lease ownership token required for refresh/release
+  - time/clock source is injectable for deterministic tests
+  - failures are typed enough for callers to distinguish “lock held” vs “unexpected error”
+- Tests exist:
+  - unit tests for condition-expression correctness and edge cases
+  - DynamoDB Local integration test proving two contenders behave correctly
+
+---
+
+### FT-T2 — Transactional update recipes (metadata + pointer swap)
+
+**Goal:** make it easy to implement “update metadata + update pointer” safely under concurrent regeneration.
+
+**Wishlist mapping:** “Transactional update recipes” (FaceTheory P0).
+
+**Acceptance criteria**
+- A doc (and optionally helper functions) exists that covers:
+  - transactional update for (lock held) → write new metadata pointer → release
+  - guarding against stale writers (lease token check, version check, or conditional expressions)
+  - etag update patterns
+- If helpers are added, they exist in Go/TS/Py with equivalent semantics and tests.
+
+---
+
+### FT-T3 — TTL-first cache table patterns (high-leverage docs + examples)
+
+**Goal:** reduce schema drift and operational pitfalls for TTL-based cache metadata tables.
+
+**Wishlist mapping:** “TTL-first cache schema guidance” (FaceTheory P1).
+
+**Acceptance criteria**
+- Guidance covers:
+  - selecting TTL attribute and TTL window strategies
+  - how to represent “freshness” vs “expiry”
+  - dealing with DynamoDB TTL deletion lag
+  - operational recommendations (alarms, hot partitions, sizing)
+- At least one example exists demonstrating:
+  - writing metadata with TTL
+  - reading and deciding fresh/stale based on `generated_at` and `revalidate_seconds`
+
+---
+
+### FT-T4 — Idempotency patterns (request-id driven regeneration)
+
+**Goal:** standardize “exactly-once-ish” regeneration and async revalidation triggers.
+
+**Wishlist mapping:** “Idempotency patterns” (FaceTheory P1).
+
+**Acceptance criteria**
+- A doc exists that maps regeneration operations to idempotency keys (request ID, cache key + version, etc).
+- The doc includes guidance for:
+  - replay safety (same request key, different payload)
+  - lock + idempotency interplay (avoid double work)
+- If helpers are added, they build on existing TableTheory patterns and are multi-language with tests.
+