Repository navigation
docs(content): reconcile stale rollup docs with native Field.summary reality - #70
Merged
Merged
Conversation
…reality Investigated the piece-level `total_*` rollups reading null and confirmed the chained `Field.summary` cascade actually works: the engine recomputes `publication.total_*` from child `content_metric` rows and cascades one level up to `piece.total_*`. All 3 seeded pieces that have publications show correct totals (e.g. 11370 = 3720 + 7650); only pieces with zero publications read null, because a parent summary is never initialized until its first child write — a cosmetic framework-level null-vs-0 behavior, not a content bug. Several docs still described the long-removed `publication_rollup` flow / a non-existent `content_rollup.hook.ts`. Reconcile them to reality: - content_publication.object.ts docstring: "STORED fields (seed/client- maintained)" → native Field.summary roll-ups that cascade to the piece. - README: fix the flows-table entry and the "Known v0 caveats" rollup note. - SPEC: replace the stale `publication_rollup` flow item with `publish_approval` and a note that the totals are native summaries. Docs/comments only — no metadata or behavior change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
Following the 9.11.0 upgrade I investigated the
content_piece.total_*rollups readingnull(flagged as a possible bug). It's not a bug — the chainedField.summarycascade works correctly.What I verified (runtime,
allenv)The rollup is a two-level chain:
content_metric.views→publication.total_*(summary) →piece.total_*(summary of the publication summary). The engine recomputes a parent summary on every child write and that write itself cascades one level up.Measured across all 14 seeded pieces:
total_views = 11370 = 3720 + 7650;2670;4200).total_views = null. A parent summary is only initialized when a child write triggers a recompute, so a piece that never had a publication keeps the column default (null) rather than0. Cosmetic, framework-level (engine.ts recomputeSummaries), pre-existing, not 9.11.0-specific.My earlier "null" reading was a sampling artifact — an OData
$filterthat silently didn't apply, returning backlog (publication-less) pieces.What this PR changes (docs/comments only)
Several docs still described the long-removed
publication_rollupflow and a non-existentcontent_rollup.hook.ts/metricRollupHook:content_publication.object.tsdocstring: "total_*… STORED fields (seed/client-maintained)" → nativeField.summaryroll-ups that cascade to the piece (matches the already-correct field-level comment andhooks/index.ts).README.md: corrected the flows-table row and the "Known v0 caveats" rollup note.SPEC.md: replaced the stalepublication_rollupflow item with the realpublish_approvalflow + a native-summary note.No metadata or behavior change.
pnpm --filter @objectlab/content buildgreen,pnpm format:checkclean.🤖 Generated with Claude Code