Skip to content

[P2] Aspirational-config disposition: reconcile-or-prune the still-dead props from the 2026-06 liveness audit (Theme / Translation / Job / Webhook) #3494

Closed

Description

@os-zhuang

Context

Follow-up to the 2026-06-15 system/integration liveness audit (docs/audits/2026-06-system-integration-property-liveness.md), which flagged a cluster of aspirational metadata props — parsed by the spec, read by no runtime, so authoring them is a silent no-op. The earlier aspirational-config issue #1893 (umbrella #1878) is closed, but for most of these rows the only action taken was adding an [EXPERIMENTAL — not enforced] describe comment — an honesty label, not a disposition. Portal (the worst offender) was actually pruned in #3464 following the same enforce-or-remove treatment as #2377.

This issue tracks the permanent disposition (reconcile / build / prune) of the props from that audit that are still dead on main. Re-verified against origin/main @ 189854cbc (2026-07); each item carries file:line evidence.

Excluded — already fixed (do not re-litigate)

  • EmailTemplateSchema "worst drift case" — the audit's headline finding (a live email_template type bound to a spec shape that didn't match the sys_email_template row) is resolved, and the fix predates the audit. email_template now binds the shape-aligned EmailTemplateDefinitionSchema (packages/spec/src/kernel/metadata-type-schemas.ts:101; new file packages/spec/src/system/email-template.zod.ts), consumed by the runtime email plugin (packages/plugins/plugin-email/src/auth-templates.ts:3), with sys_email_template rows mapping field-for-field. Fix: commit 47a92f427 (2026-05-29). The audit row appears to have read a stale (EmailTemplateSchema) comment.
    • Optional low-pri cleanup only (not part of this issue's scope): the orphan legacy EmailTemplateSchema (packages/spec/src/system/notification.zod.ts:30, body/bodyType) and the stale (EmailTemplateSchema) comment at metadata-plugin.zod.ts:110.

Still dead — needs disposition

For each, pick A — prune (remove the dead props/exports; minor + changeset migration note, per the #3464 precedent) or B — build (wire a real consumer).

1. Theme — 7 dead props (+ 1 regressed)

spacing, breakpoints, logo, density, rtl, touchTarget, keyboardNavigation are merged by mergeThemes but never emitted as CSS vars. wcagContrast was PARTIAL in the audit (via a meetsContrastLevel helper) — that helper no longer exists (0 hits), so it is now fully dead.

  • Evidence: packages/spec/src/ui/theme.zod.ts:226 ("generateThemeVars does not emit spacing tokens yet"), :235 (breakpoints), plus similar self-admissions for density/rtl/touchTarget.
  • Cross-repo caveat: the real theme engine lives in the external objectui repo (this monorepo has no ThemeEngine / mergeThemes / generateThemeVars implementation — 0 hits, only a .objectui-sha pointer). Liveness here is inferred from (a) no local consumer and (b) the spec's own describe text admitting "not emitted yet". Before pruning, confirm with objectui that no external renderer reads these — this one is not the clean local-only kill Portal was.
  • Current state: spacing/breakpoints/density/rtl/touchTarget carry the experimental note; logo/keyboardNavigation/wcagContrast do not.
  • Disposition: A prune (if objectui confirms no consumer) / B emit them as CSS vars in generateThemeVars.

2. Translation — 4 dead knobs (audit's 5th is not actually dead)

  • messageFormat — no ICU engine exists anywhere; messageFormat:'icu' is accepted but interpolation falls back to simple substitution. Self-admitted at packages/spec/src/system/translation.zod.ts:451. This is the "unkept promise" the audit called out.
  • fileOrganization, lazyLoad, cache — no runtime reader (translation.zod.ts:455: "No runtime consumer reads this cache flag yet").
  • Correction to the audit: supportedLocales is not fully dead — packages/cli/src/commands/serve.ts:743 reads it to toggle pinyin-search (any zh-* → on). It still doesn't drive locale resolution, so if scoped here the wording must be "doesn't drive i18n locale set", not "no consumer". Leave it.
  • Related (not a prune target): the kernel memory-fallback path uses a heuristic resolveLocale() (packages/core/src/fallbacks/memory-i18n.ts:45) rather than the configured fallbackLocale; the real I18nServicePlugin path does receive fallbackLocale, so this is a memory-fallback-only nuance.
  • Disposition: messageFormat:'icu' — A drop the enum value (keep 'simple') / B wire an ICU engine. fileOrganization/lazyLoad/cache — A prune.

3. Job — retryPolicy / timeout

The cron adapter's execute() (packages/services/service-job/src/cron-job-adapter.ts:147-158) only try { handler } catch { log } — no retry, backoff, or timeout — despite the fully-specced RetryPolicySchema (packages/spec/src/system/job.zod.ts:55). git grep -E "retryPolicy|timeout" -- packages/services/service-job/src = 0 hits. Self-admitted at job.zod.ts:90-91. (The only retry/backoff in the repo is in service-queue, a different subsystem.)

  • Disposition: B build (have the cron adapter honor retryPolicy/timeout — these are semantics authors reasonably expect) is arguably preferable to pruning a genuinely useful feature; A prune if job-level retry is not planned.

4. Webhook — dead props + a fully-dead sub-schema + naming drift

Outbound delivery runs entirely off the sys_webhook row + auto-enqueuer.ts; git grep -E "payloadFields|includeSession|retryPolicy|\.body" -- packages/plugins/plugin-webhooks = 0 hits.

  • Dead outbound props: body, payloadFields, includeSession, authentication non-HMAC branches (bearer/basic/api-key — only secret→HMAC is applied, webhook.zod.ts:102, auto-enqueuer.ts:276/334), retryPolicy (owned by the outbox/queue), description, tags.
  • WebhookReceiverSchema (inbound) — entirely dead: defined packages/spec/src/automation/webhook.zod.ts:141, type export :161, no other reference repo-wide. This is a Portal-class fully-dead schema and the cleanest prune candidate here.
  • Naming drift (latent bug): schema object → row object_name (auto-enqueuer.ts:267), schema isActive → row active (auto-enqueuer.ts:176); everything else (headers/auth/retry/payload) only lives inside definition_json and the UI can only toggle active (sys-webhook.object.ts:41-43).
  • Disposition: WebhookReceiverSchema — A prune (fully dead). Non-HMAC auth / payloadFields — B build (real webhook features) or A prune. Naming drift — reconcile the field names or document the mapping.

Suggested per-item disposition

Item Still dead? Suggested
Theme 7 props (spacing/breakpoints/logo/density/rtl/touchTarget/keyboardNavigation) + wcagContrast Yes (locally) Confirm with objectui → prune if unconsumed
Translation messageFormat:'icu' Yes prune enum value (or build ICU)
Translation fileOrganization/lazyLoad/cache Yes prune
Translation supportedLocales No — has a reader keep; fix audit wording
Job retryPolicy/timeout Yes build (or prune if not planned)
Webhook WebhookReceiverSchema Yes (fully) prune
Webhook body/payloadFields/includeSession/non-HMAC auth/retryPolicy/description/tags Yes prune (build the ones deemed valuable)
Webhook object/isActive naming drift Yes reconcile or document
EmailTemplate drift No — fixed (47a92f427) excluded

Refs: umbrella #1878, closed #1893 (aspirational config), precedent #3464 (Portal prune), audit docs/audits/2026-06-system-integration-property-liveness.md.

Activity

  1. os-zhuang commented on Jul 27, 2026

    @os-zhuang
    ContributorAuthor

    Close-out — both PRs merged

    Every still-dead row now has its permanent disposition. Verified per-item outcome:

    Item Disposition Landed in
    Theme spacing/breakpoints/logo/density/wcagContrast/rtl/touchTarget/keyboardNavigation (+ dedicated sub-schemas & types) Pruned — re-verified against the objectui theme engine before deletion: generateThemeVars (objectui packages/core/src/theme/ThemeEngine.ts) consumes colors/typography/borderRadius/shadows/animation/zIndex/customVars only #3516
    Translation fileOrganization/messageFormat/lazyLoad/cache (+ MessageFormatSchema, TranslationFileOrganizationSchema) Pruned — no ICU engine exists; interpolation is always simple {variable} substitution. File layout stays documented as a pure authoring convention #3516
    Translation supportedLocales Kept — live reader (pinyin-search toggle, serve.ts:743); the audit's "no consumer" wording was stale —
    Webhook body/payloadFields/includeSession/authentication (non-HMAC)/retryPolicy/tags + entire inbound WebhookReceiverSchema Pruned — delivery sends its fixed envelope, HMAC-via-secret stays, outbox owns its own retry schedule; the #3489 materializer reads none of the removed fields. Ledger entries for removed props dropped; the dead→live flip for the materialized props remains #3490's scope #3516
    Webhook object→object_name / isActive→active naming drift Resolved by the #3489 bridge (mapWebhookToRow remaps); documenting it in the refreshed ledger is part of #3490 —
    Job retryPolicy / timeout Built — IJobService.schedule gains an optional options arg; runWithPolicy enforces exponential-backoff retries and a per-attempt timeout (execution status 'timeout') across Cron/Interval/Db adapters; AppPlugin forwards the authored values. Tests verified red-then-green; [EXPERIMENTAL] markers removed from the schema #3529
    EmailTemplate "worst drift" Excluded — already fixed by 47a92f427 before the audit was written —

    Versioning: both PRs ride the minor line with feat(spec)!: titles + migration notes, per the #2377/#3464 enforce-or-remove precedent.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions