refactor(core-utils): Deprecate assert for external use

[Joshua Smithrud (Josmithr)]

The legacy assert API is intended only for use within the Fluid Framework client codebase and is now deprecated for external consumers.
Consumers should replace it with an assertion utility appropriate for their application.

Usage within the Fluid Framework client is still permitted.

Existing usages of assert in example apps were replaced with Errors.

[github-actions]

Hi! Thank you for opening this PR. Want me to review it?

Based on the diff (434 lines, 41 files), I've queued these reviewers:

• Correctness — logic errors, race conditions, lifecycle issues
• Security — vulnerabilities, secret exposure, injection
• API Compatibility — breaking changes, release tags, type design
• Performance — algorithmic regressions, memory leaks
• Testing — coverage gaps, hollow tests

How this works

• Adjust the reviewer set by ticking/unticking boxes above. Reviewer toggles alone don't trigger anything.

• Tick Start review below to dispatch the review fleet.

• After review finishes, tick Start review again to request another run — it auto-resets after each dispatch.

• This comment updates as new commits land; your reviewer selections are preserved.

• Start review

[Copilot]

Pull request overview

This PR deprecates the external assert export from @fluidframework/core-utils while preserving a non-deprecated assertion API for Fluid-internal consumers via a dedicated @fluidframework/core-utils/internal entry point. It also updates examples to stop relying on the deprecated external assert.

Changes:

• Split @fluidframework/core-utils into shared (main.ts) plus external (index.ts) vs internal (internal.ts) entry points, exporting non-deprecated assert only from /internal.
• Introduce assertInternal() and route the deprecated external assert() implementation through it.
• Remove @fluidframework/core-utils usage from multiple examples (replace with explicit runtime checks / throws) and update lockfile accordingly.

Reviewed changes

Copilot reviewed 42 out of 43 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pnpm-lock.yaml	Removes @fluidframework/core-utils from several example importers after usage cleanup
packages/common/core-utils/src/timer.ts	Switches local usage to assertInternal to avoid deprecated symbol internally
packages/common/core-utils/src/math.ts	Switches local usage to assertInternal to avoid deprecated symbol internally
packages/common/core-utils/src/main.ts	New shared barrel for exports common to external + internal entry points (omits assert)
packages/common/core-utils/src/internal.ts	New internal entry point barrel that re-exports shared API + internal assert
packages/common/core-utils/src/index.ts	External entry point barrel now re-exports shared API + deprecated external assert
packages/common/core-utils/src/assert.ts	Adds assertInternal; deprecates external assert; routes assert through assertInternal
packages/common/core-utils/package.json	Updates ./internal export map to point at internal.{js,d.ts} outputs
packages/common/core-utils/DEV.md	Documents the new entry point structure and rationale
packages/common/core-utils/api-report/core-utils.legacy.beta.api.md	API report updates assert to include @deprecated
packages/common/core-utils/api-extractor/api-extractor-lint-bundle.json	Lint-bundle now uses lib/internal.d.ts as the entry point
examples/view-integration/external-views/src/container/diceRoller/diceRoller.ts	Replaces deprecated assert usage with explicit runtime validation + throw
examples/view-integration/external-views/package.json	Drops unused @fluidframework/core-utils dependency
examples/view-integration/container-views/src/container/diceRoller/diceRoller.ts	Replaces deprecated assert usage with explicit runtime validation + throw
examples/view-integration/container-views/package.json	Drops unused @fluidframework/core-utils dependency
examples/version-migration/live-schema-upgrade/src/modelVersion2/diceCounter.ts	Replaces deprecated assert checks with explicit throws
examples/version-migration/live-schema-upgrade/src/app.ts	Replaces deprecated assert checks with explicit throws
examples/version-migration/live-schema-upgrade/package.json	Drops unused @fluidframework/core-utils dependency
examples/utils/migration-tools/src/migrator/migrator.ts	Replaces deprecated assert checks with explicit throws
examples/utils/migration-tools/src/migrationTool/migrationTool.ts	Replaces deprecated assert checks with explicit throws
examples/utils/migration-tools/package.json	Drops unused @fluidframework/core-utils dependency
examples/utils/example-utils/src/migrator/sameContainerMigrator.ts	Replaces deprecated assert checks with explicit throws
examples/utils/example-utils/src/migrationTool/sameContainerMigrationTool.ts	Replaces deprecated assert checks with explicit throws
examples/utils/example-utils/package.json	Drops unused @fluidframework/core-utils dependency
examples/data-objects/webflow/src/html/formatters.ts	Replaces deprecated assert check with explicit throw
examples/data-objects/webflow/src/document/index.ts	Replaces deprecated assert check with explicit throw
examples/data-objects/webflow/package.json	Drops unused @fluidframework/core-utils dependency
examples/data-objects/table-document/src/interception/tableWithInterception.ts	Replaces deprecated assert checks with explicit throws
examples/data-objects/table-document/src/cellrange.ts	Replaces deprecated assert check with explicit throw
examples/data-objects/table-document/package.json	Drops unused @fluidframework/core-utils dependency
examples/data-objects/smde/src/smde.ts	Replaces deprecated assert check with explicit throw
examples/data-objects/smde/package.json	Drops unused @fluidframework/core-utils dependency
examples/data-objects/prosemirror/src/fluidCollabManager.ts	Replaces deprecated assert check with explicit throw
examples/data-objects/prosemirror/src/fluidBridge.ts	Replaces deprecated assert checks with explicit throws
examples/data-objects/prosemirror/package.json	Drops unused @fluidframework/core-utils dependency
examples/apps/task-selection/src/taskManagerDiceRoller.ts	Replaces deprecated assert checks with explicit throws
examples/apps/task-selection/src/oldestClientDiceRoller.ts	Replaces deprecated assert checks with explicit throws
examples/apps/task-selection/package.json	Drops unused @fluidframework/core-utils dependency
examples/apps/staging/src/container/groceryList/groceryList.ts	Replaces deprecated assert check with explicit throw
examples/apps/staging/package.json	Drops unused @fluidframework/core-utils dependency
examples/apps/presence-tracker/src/datastoreSupport.ts	Replaces deprecated assert checks with explicit throws (including a TypeError for type mismatch)
examples/apps/presence-tracker/package.json	Drops unused @fluidframework/core-utils dependency
.changeset/tricky-rules-fly.md	Adds a changeset documenting the deprecation (minor bump, deprecation section)

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Jason Hartman (jason-ha)]

I think the reason I use api.ts in telemetry-utils was to preserve the history and be able to see the actual change. But, yeah, it means touching more places in package.json.
No need to change.

[Jason Hartman (jason-ha)]

Matt Rakow (@ChumpChief), sounds like an experiment and not an example.

[github-actions]

🔗 Found some broken links! 💔

Run a link check locally to find them. See Checking for Broken Links for more information.

linkcheck output

$ start-server-and-test "npm run serve -- --host 127.0.0.1 --no-open" http://127.0.0.1:3000 check-links
1: starting server using command "npm run serve -- --host 127.0.0.1 --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-website@0.0.0 serve
> docusaurus serve --host 127.0.0.1 --no-open

[SUCCESS] Serving "build" directory at: http://127.0.0.1:3000/

> fluid-framework-website@0.0.0 check-links
> linkcheck http://127.0.0.1:3000 --skip-file skipped-urls.txt

Crawling...

http://127.0.0.1:3000/docs/data-structures/tree/schema-evolution/feature-flag-schema-upgrades
- (72:12) 'isStaged..' => http://127.0.0.1:3000/docs/api/fluid-framework/treeviewalpha-interface#isstagedupgradeenabled-methodsignature (HTTP 200 but missing anchor)


Stats:
  338443 links
    2041 destination URLs
    2297 URLs ignored
       1 warnings
       0 errors

Error: Command failed with exit code 1: npm run check-links
    at makeError (/home/runner/work/FluidFramework/FluidFramework/website/node_modules/.pnpm/execa@5.1.1/node_modules/execa/lib/error.js:60:11)
    at handlePromise (/home/runner/work/FluidFramework/FluidFramework/website/node_modules/.pnpm/execa@5.1.1/node_modules/execa/index.js:118:26)
    at process.processTicksAndRejections (node:internal/process/task_queues:103:5) {
  shortMessage: 'Command failed with exit code 1: npm run check-links',
  command: 'npm run check-links',
  escapedCommand: '"npm run check-links"',
  exitCode: 1,
  signal: undefined,
  signalDescription: undefined,
  stdout: undefined,
  stderr: undefined,
  failed: true,
  timedOut: false,
  isCanceled: false,
  killed: false
}
[ELIFECYCLE] Command failed with exit code 1.

[github-actions]

Bundle size comparison

Base commit: 480ee6fdd33a385c035446f67ff104953bac9c86
Head commit: 00046a50933a94427a3ffb718ba52528862cbd03

Pending — Build - client packages is running. Results will appear here when the build completes.