Skip to content

mdcode: address KC pull review comments (post-merge follow-up) - #298

Merged
libei merged 2 commits into
GoogleCloudPlatform:mainfrom
libei:upstream-pr6-pull-review-fixes
Aug 15, 2026
Merged

libei merged 2 commits into
GoogleCloudPlatform:mainfrom
libei:upstream-pr6-pull-review-fixes

Conversation

@libei

@libei libei commented Aug 15, 2026

Copy link
Copy Markdown
Collaborator

Follow-up to the merged #277 (semantic-model Knowledge Catalog pull leg), addressing the inline review comments left after merge. Reader / pull-orchestration / CLI only — the writer (#278) is untouched.

Changes

  • pull_kc: hard-fail on any entry-hydration fetch error and on a non-200 link lookup; an empty link list stays a silent no-op (:81, :112).
  • One model per entry group: dropped the pull --model flag; >1 anchor in a group is now a hard error naming both (:483, :261, :140).
  • pull --force-remove: authorize replacing a differently-named local model with the catalog's, rather than silently leaving two models in the group (:269).
  • Schema-join link type is a fixed built-in constant, never undefined (:108, :182).
  • push: warn when a relationship name will be normalized — KC stores the name only in the link id, so a pull returns it lowercased/hyphenated (:295).
  • Typeless defaults: untyped fields and metrics now default to Opaque (STRING + OTHER) instead of guessing STRING/NUMERIC; a typeless metric round-trips un-typed (:296).
  • osi_schema guardrail: the .pull.golden.yaml fixtures come from a default (expression-free) KC push, so their fields/metrics lack the OSI-required expression. They're excluded from the OSI schema check with a TODO(#290)mdcode: store SQL expressions in the sql-expressions companion aspect #290 (the sql-expressions companion aspect) restores expressions on push+pull, at which point they can be schema-checked again.
  • Docs (docs/semantic-model.md) + tests + regenerated goldens to match.

Deferred (tracked as follow-ups, not in this PR)

  • Recover entity keys (pk/unique) on pull → schema aspect.
  • Recover ai_context on pull → guidelines aspect.
  • Recover field labels on pull → schema aspect annotations.

Testing

bun test — green (the one local ajv/dist/2020 load error is a borrowed-node_modules artifact; ajv ^8.17.1 is a declared devDependency so CI resolves it).

Follow-up to the merged PR GoogleCloudPlatform#277 (semantic-model KC pull leg), addressing
dlychagin-gg's inline review. Reader/orchestration/CLI only; the writer is
untouched.

- pull_kc: hard-fail on any entry-hydration fetch error and on a non-200
  link lookup; an empty link list stays a silent no-op.
- Enforce one semantic model per entry group: drop the `--pull --model`
  flag; >1 anchor is a hard error naming both.
- Add `pull --force-remove` to authorize replacing a differently-named
  local model with the catalog's, rather than leaving two in the group.
- Schema-join link type is a fixed built-in constant, never undefined.
- push: warn when a relationship name will be normalized (KC stores it
  only in the link id, so a pull returns it lowercased/hyphenated).
- Default untyped fields and metrics to Opaque (STRING + OTHER) instead of
  guessing STRING/NUMERIC; a typeless metric now round-trips un-typed.
- osi_schema: exclude the expression-free .pull.golden.yaml fixtures from
  the OSI guardrail with a TODO(GoogleCloudPlatform#290); PR GoogleCloudPlatform#290 restores expressions on
  push+pull, at which point they can be schema-checked again.
- Docs + tests + regenerated goldens to match.
Follow-up fixes from a review pass over the pull review-fixes PR:

- pull reconcile compares local vs catalog models by their on-disk path,
  not the raw name, so a model name that sanitizes to the same file (e.g.
  'a/b' -> 'a_b.yaml') is recognized as the same model rather than flagged
  as a stale conflict on every re-pull.
- mapConcurrent stops claiming new items once a worker throws: Promise.all
  already rejects on the first failure, so the remaining fan-out was wasted
  fetches whose rejections surfaced as unhandled-rejection noise.
- the OSI guardrail now validates .pull.golden.yaml fixtures too, tolerating
  ONLY the known missing-`expression` gap (TODO GoogleCloudPlatform#290) instead of skipping
  them by filename -- so unrelated schema drift is caught now, and the
  fixtures schema-check with no special-casing once GoogleCloudPlatform#290 restores
  expressions.
@libei

libei commented Aug 15, 2026

Copy link
Copy Markdown
Collaborator Author

Follow-up commit b2ee552 from a self-review pass:

  • Pull reconcile compares by on-disk path, not raw name. A model name that sanitizes to the same file (e.g. a/ba_b.yaml) was flagged as a stale conflict on every re-pull because catalogNames held the raw name while modelDocuments() returns filename-derived names. Now both sides are compared through modelPath.
  • mapConcurrent stops fanning out after the first failure. Promise.all already rejects on the first throw, so the remaining workers' fetches were wasted work whose rejections surfaced as unhandled-rejection noise; a shared failed flag now halts new claims.
  • OSI guardrail validates the .pull.golden.yaml fixtures too, tolerating only the known missing-expression gap (TODO mdcode: store SQL expressions in the sql-expressions companion aspect #290) rather than skipping them by filename — so unrelated schema drift is caught today, and the fixtures schema-check with no special-casing once mdcode: store SQL expressions in the sql-expressions companion aspect #290 restores expressions (verified: all three fail only with required:expression).

Deferred, intentionally not in this commit:

tsc clean; full suite 330 pass / 0 fail.

@libei
libei marked this pull request as ready for review August 15, 2026 03:41
@libei
libei merged commit 3c3665e into GoogleCloudPlatform:main Aug 15, 2026
7 checks 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