Skip to content

feat(spec)!: remove the dead PortalSchema — never-enforced no-op projection (#3464) - #3486

Merged
os-zhuang merged 1 commit into
mainfrom
feat/prune-portal-schema-3464
Jul 25, 2026
Merged

feat(spec)!: remove the dead PortalSchema — never-enforced no-op projection (#3464)#3486
os-zhuang merged 1 commit into
mainfrom
feat/prune-portal-schema-3464

Conversation

@os-zhuang

Copy link
Copy Markdown
Contributor

What & why

Issue #3464 disposition A — prune. PortalSchema (packages/spec/src/ui/portal.zod.ts, ~350 lines) was the largest dead schema in the spec: not registered as a metadata type, no dispatcher route family / auth scope / renderer consumer, and already marked [EXPERIMENTAL — not enforced] with "authoring a portal today is a no-op". This removes it rather than building a portal runtime (disposition B).

Changes

  • Spec: delete ui/portal.zod.ts + ui/portal.test.ts; drop the portals collection from StackSchema / defineStack() and every Portal* export. A comment records the removal next to the apps key (matching the ADR-0019/0020 removed-collection precedent).
  • Showcase: remove the dead ClientPortal fixture (src/ui/portals/) and its config wiring. The client_portal_user position and guest_portal permission set stay — independent security metadata that only shares the word "portal".
  • Generated artifacts regenerated in-PR: api-surface.json (−28), json-schema.manifest.json (−13 keys), content/docs/references/ui/portal.mdx removed.
  • Hand-written docs/skills stop advertising portals as a live surface (content/docs/ui/index.mdx, skills/objectstack-platform/SKILL.md, docs/NEXT_STEP.md). The real public-forms path (guest_portal + anonymous entry) is untouched — it never depended on PortalSchema.

Versioning

@objectstack/specminor, matching the #2377 enforce-or-remove pruning precedent and satisfying the launch-window no-major guard (check-changeset-no-major.mjs). The changeset carries the migration note: authoring a portal had no runtime effect, so there is no behavioral migration — drop any portals: [...] from a defineStack() config (now an excess-property type error). To project a scoped UI to external users today, compose apps / views and gate admission with positions + permission sets.

Verification

  • turbo type-check --force (full repo, cache-busted) ✓
  • @objectstack/spec vitest: 257 files / 6850 tests ✓
  • spec drift gates: check:api-surface, check:docs, check:spec-changes, check:upgrade-guide, check:liveness, check:skill-refs, check:skill-docs
  • root gates: check:doc-authoring, check:role-word, check:nul-bytes

Fixes#3464.

🤖 Generated with Claude Code

…ection (#3464)
PortalSchema and its StackSchema `portals` collection were a forward-looking
design that was never wired to a runtime: no metadata-type registration, no
dispatcher route family, no auth scope, and no LayoutDispatcher /
NavigationBuilder / ThemeProvider consumer. Authoring a portal was already a
documented no-op marked [EXPERIMENTAL — not enforced]. This implements issue
#3464 disposition A (prune the dead schema) rather than B (build a runtime).
Removes ui/portal.zod.ts + its test, the `portals` key on StackSchema /
defineStack, every Portal* export, the showcase ClientPortal fixture, and the
generated Portal artifacts (json-schema manifest keys, api-surface entries,
reference doc). Hand-written docs/skills stop advertising portals as a live
surface; the real guest_portal public-forms path is left untouched.
Versioned minor per the #2377 enforce-or-remove precedent and the launch-window
no-major guard.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vercel

vercelBot commented Jul 25, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

ProjectDeploymentActionsUpdated (UTC)
specReadyReadyPreview, CommentJul 25, 2026 2:50am

Request Review

@github-actionsgithub-actionsBot added documentation Improvements or additions to documentation tests protocol:ui tooling size/xl labels Jul 25, 2026
@github-actions

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec.

104 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

  • content/docs/ai/agents.mdx(via @objectstack/spec)
  • content/docs/ai/skills-reference.mdx(via @objectstack/spec)
  • content/docs/ai/skills.mdx(via @objectstack/spec)
  • content/docs/api/client-sdk.mdx(via @objectstack/spec)
  • content/docs/api/environment-routing.mdx(via @objectstack/spec)
  • content/docs/api/error-catalog.mdx(via @objectstack/spec)
  • content/docs/api/error-handling-client.mdx(via @objectstack/spec)
  • content/docs/api/error-handling-server.mdx(via @objectstack/spec)
  • content/docs/api/index.mdx(via @objectstack/spec)
  • content/docs/automation/approvals.mdx(via packages/spec)
  • content/docs/automation/flows.mdx(via @objectstack/spec)
  • content/docs/automation/hook-bodies.mdx(via packages/spec)
  • content/docs/automation/hooks.mdx(via @objectstack/spec)
  • content/docs/automation/index.mdx(via @objectstack/spec)
  • content/docs/automation/webhooks.mdx(via @objectstack/spec)
  • content/docs/automation/workflows.mdx(via @objectstack/spec)
  • content/docs/concepts/architecture.mdx(via @objectstack/spec)
  • content/docs/concepts/design-principles.mdx(via packages/spec)
  • content/docs/concepts/index.mdx(via @objectstack/spec)
  • content/docs/concepts/metadata-driven.mdx(via @objectstack/spec)
  • content/docs/concepts/metadata-lifecycle.mdx(via packages/spec)
  • content/docs/concepts/north-star.mdx(via packages/spec)
  • content/docs/data-modeling/analytics.mdx(via @objectstack/spec)
  • content/docs/data-modeling/drivers.mdx(via @objectstack/spec)
  • content/docs/data-modeling/external-datasources.mdx(via @objectstack/spec)
  • content/docs/data-modeling/field-types.mdx(via @objectstack/spec)
  • content/docs/data-modeling/fields.mdx(via @objectstack/spec)
  • content/docs/data-modeling/formulas.mdx(via @objectstack/spec)
  • content/docs/data-modeling/index.mdx(via @objectstack/spec)
  • content/docs/data-modeling/objects.mdx(via @objectstack/spec)
  • content/docs/data-modeling/queries.mdx(via @objectstack/spec)
  • content/docs/data-modeling/schema-design.mdx(via @objectstack/spec)
  • content/docs/data-modeling/seed-data.mdx(via @objectstack/spec)
  • content/docs/data-modeling/validation-rules.mdx(via @objectstack/spec)
  • content/docs/data-modeling/validation.mdx(via @objectstack/spec)
  • content/docs/deployment/cli.mdx(via @objectstack/spec)
  • content/docs/deployment/troubleshooting.mdx(via @objectstack/spec)
  • content/docs/deployment/validating-metadata.mdx(via @objectstack/spec)
  • content/docs/getting-started/build-with-claude-code.mdx(via @objectstack/spec)
  • content/docs/getting-started/common-patterns.mdx(via @objectstack/spec)
  • content/docs/getting-started/examples.mdx(via @objectstack/spec)
  • content/docs/getting-started/quick-reference.mdx(via @objectstack/spec)
  • content/docs/getting-started/quick-start.mdx(via @objectstack/spec)
  • content/docs/getting-started/your-first-project.mdx(via @objectstack/spec)
  • content/docs/kernel/cluster.mdx(via @objectstack/spec)
  • content/docs/kernel/contracts/auth-service.mdx(via packages/spec)
  • content/docs/kernel/contracts/cache-service.mdx(via packages/spec)
  • content/docs/kernel/contracts/data-engine.mdx(via @objectstack/spec)
  • content/docs/kernel/contracts/index.mdx(via @objectstack/spec)
  • content/docs/kernel/contracts/metadata-service.mdx(via packages/spec)
  • content/docs/kernel/contracts/storage-service.mdx(via packages/spec)
  • content/docs/kernel/index.mdx(via packages/spec)
  • content/docs/kernel/runtime-services/email-service.mdx(via packages/spec)
  • content/docs/kernel/runtime-services/index.mdx(via packages/spec)
  • content/docs/kernel/runtime-services/queue-service.mdx(via packages/spec)
  • content/docs/kernel/runtime-services/sharing-service.mdx(via packages/spec)
  • content/docs/kernel/runtime-services/sms-service.mdx(via packages/spec)
  • content/docs/kernel/runtime-services/storage-service.mdx(via packages/spec)
  • content/docs/kernel/services-checklist.mdx(via @objectstack/spec)
  • content/docs/permissions/authorization.mdx(via @objectstack/spec)
  • content/docs/permissions/permission-sets.mdx(via @objectstack/spec)
  • content/docs/permissions/permissions-matrix.mdx(via @objectstack/spec)
  • content/docs/permissions/positions.mdx(via @objectstack/spec)
  • content/docs/permissions/rls.mdx(via @objectstack/spec)
  • content/docs/permissions/sharing-rules.mdx(via @objectstack/spec)
  • content/docs/plugins/adding-a-metadata-type.mdx(via @objectstack/spec)
  • content/docs/plugins/development.mdx(via @objectstack/spec)
  • content/docs/plugins/index.mdx(via @objectstack/spec)
  • content/docs/plugins/packages.mdx(via @objectstack/spec)
  • content/docs/protocol/backward-compatibility.mdx(via @objectstack/spec)
  • content/docs/protocol/diagram.mdx(via packages/spec)
  • content/docs/protocol/kernel/config-resolution.mdx(via @objectstack/spec)
  • content/docs/protocol/kernel/i18n-standard.mdx(via @objectstack/spec)
  • content/docs/protocol/kernel/index.mdx(via @objectstack/spec)
  • content/docs/protocol/kernel/lifecycle.mdx(via @objectstack/spec)
  • content/docs/protocol/kernel/plugin-spec.mdx(via @objectstack/spec)
  • content/docs/protocol/kernel/runtime-capabilities.mdx(via @objectstack/spec)
  • content/docs/protocol/knowledge.mdx(via @objectstack/spec)
  • content/docs/protocol/objectql/index.mdx(via @objectstack/spec)
  • content/docs/protocol/objectql/query-syntax.mdx(via @objectstack/spec)
  • content/docs/protocol/objectql/schema.mdx(via @objectstack/spec)
  • content/docs/protocol/objectql/security.mdx(via packages/spec)
  • content/docs/protocol/objectql/state-machine.mdx(via @objectstack/spec)
  • content/docs/protocol/objectui/actions.mdx(via @objectstack/spec)
  • content/docs/protocol/objectui/concept.mdx(via @objectstack/spec)
  • content/docs/protocol/objectui/index.mdx(via @objectstack/spec)
  • content/docs/protocol/objectui/layout-dsl.mdx(via @objectstack/spec)
  • content/docs/protocol/objectui/record-alert.mdx(via @objectstack/spec)
  • content/docs/protocol/objectui/widget-contract.mdx(via @objectstack/spec)
  • content/docs/releases/implementation-status.mdx(via @objectstack/spec)
  • content/docs/releases/index.mdx(via @objectstack/spec)
  • content/docs/releases/v12.mdx(via @objectstack/spec)
  • content/docs/releases/v13.mdx(via @objectstack/spec)
  • content/docs/releases/v16.mdx(via @objectstack/spec)
  • content/docs/releases/v9.mdx(via @objectstack/spec)
  • content/docs/ui/actions.mdx(via @objectstack/spec)
  • content/docs/ui/create-vs-edit-form.mdx(via @objectstack/spec)
  • content/docs/ui/dashboards.mdx(via @objectstack/spec)
  • content/docs/ui/forms.mdx(via @objectstack/spec)
  • content/docs/ui/index.mdx(via @objectstack/spec)
  • content/docs/ui/public-data-collection.mdx(via @objectstack/spec)
  • content/docs/ui/setup-app.mdx(via @objectstack/spec)
  • content/docs/ui/translations.mdx(via @objectstack/spec)
  • content/docs/ui/views.mdx(via @objectstack/spec)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

@os-zhuang
os-zhuang merged commit 8269e32 into mainJul 25, 2026
17 checks passed
@os-zhuang
os-zhuang deleted the feat/prune-portal-schema-3464 branch July 25, 2026 02:59
xuyushun441-sys pushed a commit that referenced this pull request Jul 27, 2026
…phQL removal follow-through)
- Changeset major → minor per the launch-window convention (the gate's
own instruction; same treatment as #3486/#2377 — breaking rides minor
without burning the whole fixed group's major).
- Drop the api/graphql.zod.ts entry from the skill-references mapping
and regenerate (check:skill-refs gate).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
os-zhuang added a commit that referenced this pull request Jul 27, 2026
* feat(spec)!: remove the never-implemented GraphQL surface (#2462 follow-on)
Product decision: GraphQL is not on the plan. It was schema-only from
day one — 20+ spec config schemas, an unconditionally-501 handleGraphQL
(kernel.graphql never assigned in the monorepo), and THREE separate
mounts (dispatcher if-chain, dispatcher-plugin hono route, hono adapter)
advertising the dead endpoint: the "declared ≠ mounted ≠ implemented"
seam disease in one picture.
Removed: spec schemas/contracts/enum members (CoreServiceName,
ApiProtocolType, query dialects, graphql-playground), capability
booleans, discovery/router fields, all three runtime mounts, the
discovery advertisement, plugin-dev stubs, the now-dead
resolveRequestExecutionContext, qa conformance rows + ratchet pins +
dogfood surface cases, generated JSON-schema manifest keys + reference
docs, and handwritten doc mentions.
Kept deliberately: external-datasource 'graphql' protocol option (third
parties may speak GraphQL to us as a CLIENT) and cloud's reserved slug.
objectui's own dead 'graphql' union member noted for cross-repo cleanup.
Verified: full monorepo build+test forced, 131 tasks green (spec 6675,
core 386, runtime 647, dogfood 60, conformance 41 among them);
api-surface + json-schema manifest + reference docs regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: launch-window changeset level + regenerate skill references (GraphQL removal follow-through)
- Changeset major → minor per the launch-window convention (the gate's
own instruction; same treatment as #3486/#2377 — breaking rides minor
without burning the whole fixed group's major).
- Drop the api/graphql.zod.ts entry from the skill-references mapping
and regenerate (check:skill-refs gate).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
os-zhuang added a commit that referenced this pull request Jul 27, 2026
…drop re-exports — ADR-0076 Step 2 PR-C (#2462) (#3591)
- assembleMetadataProtocol() in metadata-protocol is now the ONE
assembly (objects + protocol shim + D12 degraded analytics);
createMetadataProtocolPlugin (cloud/delegated) and ObjectQLPlugin's
registerProtocol convenience mode both mount it (~112 inline lines
deleted from the engine plugin; the shim return feeds the engine's
mutation-rebind subscription synchronously).
- objectql's six protocol re-exports removed (breaking-as-minor per
launch-window, #3486/#3488 precedent). Five known importers
repointed (rest x3 tests, runtime seed-loader re-export + its
integration test); runtime gains the direct metadata-protocol dep.
- Recipe correction (recorded on #2462): the objectql→metadata-protocol
DEPENDENCY stays — ./core was already protocol-free, and forcing ~20
framework boot sites to mount two plugins is a pure boilerplate tax.
Step 2's goal lands as "zero assembly ownership, single source".
Verified: full build; objectql 1086, rest 380, runtime 653, dogfood
60/61 in parallel (semantic-roles 10s-hook flake passes solo).
Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentationprotocol:uisize/xlteststooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[P2] PortalSchema disposition: prune the dead schema or build a portal runtime

1 participant

@os-zhuang