Draft CAND-0018 Capability Contract Boundary from a screened AI-chat lead
history/260927-ComplexWebAppUiComponents_chatgpt.txt is a pasted AI-chat transcript on UI-integration architecture. It fails this repo's primary-source bar (unauthored, unverifiable broken citation markers), so it is screened as a leads-only document, not cataloged as a source, and never cited as evidence. Instead read the two real specs it pointed to: MDN Custom Elements (SRC-0046) and webpack Module Federation (SRC-0047). Neither defines a semantic UI capability contract (inputs/events/commands/slots) as a first-class concept; that gap motivates the new draft hypothesis, distinct from the existing Independent Feature Boundary (release cadence) and Vertical Feature Slice (source grouping) candidates. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Assistant: claude-code Assistant-Model: sonnet Assistant-Process: 290719@bnt-lap001 Assistant-Session: 55cbe504-1bfe-4932-b761-29016523c87b
This commit is contained in:
parent
fad8abdc2c
commit
eaa1608771
7 changed files with 657 additions and 4 deletions
480
history/260927-ComplexWebAppUiComponents_chatgpt.txt
Executable file
480
history/260927-ComplexWebAppUiComponents_chatgpt.txt
Executable file
|
|
@ -0,0 +1,480 @@
|
|||
## Prompt
|
||||
|
||||
Is there a best practice for providing ui components to complex web application ui environments integrating multiple user interfaces and interface components?
|
||||
|
||||
## Exploration
|
||||
|
||||
Yes. For a complex web application that needs to integrate multiple user interfaces, teams, frameworks, or independently evolving components, there is a fairly mature set of practices—but not one single pattern. The useful way to think about it is as an **integration architecture with several layers**, rather than merely as a component library.
|
||||
|
||||
A good default architecture today looks roughly like this:
|
||||
|
||||
```text
|
||||
Application Shell
|
||||
│
|
||||
├── UX / Design System
|
||||
│ ├── design tokens
|
||||
│ ├── primitive components
|
||||
│ └── interaction conventions
|
||||
│
|
||||
├── UI Integration Contract
|
||||
│ ├── inputs / properties
|
||||
│ ├── outputs / events
|
||||
│ ├── commands
|
||||
│ ├── lifecycle
|
||||
│ └── capability metadata
|
||||
│
|
||||
├── Application Components
|
||||
│ ├── search-ui
|
||||
│ ├── customer-editor
|
||||
│ ├── document-viewer
|
||||
│ └── reporting-ui
|
||||
│
|
||||
├── Composition Layer
|
||||
│ ├── routing
|
||||
│ ├── layout
|
||||
│ ├── authentication context
|
||||
│ ├── shared state
|
||||
│ └── event/message bus
|
||||
│
|
||||
└── Runtime Integration
|
||||
├── ordinary packages
|
||||
├── Web Components
|
||||
├── module federation
|
||||
├── micro-frontends
|
||||
└── iframe/process isolation when necessary
|
||||
```
|
||||
|
||||
The important distinction is that these layers solve **different problems**.
|
||||
|
||||
### 1. Use a design system for visual and interaction coherence
|
||||
|
||||
A design system should define things such as typography, spacing, colors, accessibility conventions, buttons, dialogs, forms, navigation, tables, notifications, etc.
|
||||
|
||||
But a design system alone is not enough. It tells you that all applications should use the same sort of `<Button>`; it does not tell the host application how a `CustomerEditor` announces that a customer was saved.
|
||||
|
||||
I would therefore keep **design-system contracts** separate from **application-component contracts**.
|
||||
|
||||
---
|
||||
|
||||
### 2. Prefer framework-neutral contracts at integration boundaries
|
||||
|
||||
Inside an application, React-to-React or Vue-to-Vue component APIs are perfectly reasonable.
|
||||
|
||||
Across independently developed systems, however, tying the integration contract to:
|
||||
|
||||
```tsx
|
||||
<CustomerEditor
|
||||
customer={customer}
|
||||
onSaved={...}
|
||||
/>
|
||||
```
|
||||
|
||||
creates fairly strong coupling to React, its version, its rendering model, and often its state-management conventions.
|
||||
|
||||
A more durable boundary is something conceptually like:
|
||||
|
||||
```html
|
||||
<customer-editor customer-id="4711">
|
||||
</customer-editor>
|
||||
```
|
||||
|
||||
with:
|
||||
|
||||
```text
|
||||
attributes / properties -> configuration and input
|
||||
DOM events -> observations/output
|
||||
methods -> explicit commands
|
||||
slots -> host-provided presentation
|
||||
CSS custom properties -> theming
|
||||
```
|
||||
|
||||
That is exactly the architectural territory that **Web Components** were designed for. Custom Elements give you browser-native component boundaries, while Shadow DOM can provide DOM/CSS isolation. :chatgpt-content-reference{index="0"}
|
||||
|
||||
This doesn't imply that you have to write applications without React, Vue, Svelte, Lit, etc. A Web Component can simply be the **published interoperability surface** around an implementation written using another technology.
|
||||
|
||||
---
|
||||
|
||||
### 3. Treat coarse-grained UI capabilities differently from widgets
|
||||
|
||||
There is an important granularity boundary.
|
||||
|
||||
Things such as:
|
||||
|
||||
```text
|
||||
Button
|
||||
Checkbox
|
||||
DatePicker
|
||||
Popover
|
||||
DataGrid
|
||||
```
|
||||
|
||||
are design-system components.
|
||||
|
||||
Things such as:
|
||||
|
||||
```text
|
||||
CustomerSearch
|
||||
InvoiceEditor
|
||||
DocumentViewer
|
||||
UserAdministration
|
||||
OrderWorkbench
|
||||
```
|
||||
|
||||
are better thought of as **UI capabilities**.
|
||||
|
||||
The latter should have explicit contracts and should often be independently versionable.
|
||||
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
component: customer-editor
|
||||
version: 2.3
|
||||
|
||||
requires:
|
||||
- identity.user
|
||||
- customer.read
|
||||
- customer.write
|
||||
|
||||
inputs:
|
||||
customerId: string
|
||||
mode: [view, edit]
|
||||
|
||||
events:
|
||||
- customer-selected
|
||||
- customer-updated
|
||||
- editing-cancelled
|
||||
|
||||
commands:
|
||||
- reload
|
||||
- focus
|
||||
- reset
|
||||
|
||||
slots:
|
||||
- toolbar
|
||||
- footer
|
||||
|
||||
context:
|
||||
- locale
|
||||
- theme
|
||||
- tenant
|
||||
```
|
||||
|
||||
This starts to look less like a component API and more like a **small interface definition language for UI capabilities**. For large systems, I think this is the more useful abstraction.
|
||||
|
||||
---
|
||||
|
||||
### 4. Separate *composition* from *implementation*
|
||||
|
||||
A common architectural mistake is letting every component know how the application fits together.
|
||||
|
||||
Instead:
|
||||
|
||||
```text
|
||||
Component:
|
||||
"I can edit a customer."
|
||||
|
||||
Shell:
|
||||
"You appear here,
|
||||
for this tenant,
|
||||
with this identity,
|
||||
at this route,
|
||||
beside these other capabilities."
|
||||
```
|
||||
|
||||
The application shell should generally own:
|
||||
|
||||
- routing
|
||||
- navigation
|
||||
- page layout
|
||||
- authentication/session context
|
||||
- authorization decisions
|
||||
- locale
|
||||
- theme
|
||||
- notifications
|
||||
- observability
|
||||
- feature flags
|
||||
- capability discovery
|
||||
- failure boundaries
|
||||
|
||||
Individual UI capabilities should own their domain interaction.
|
||||
|
||||
This is very similar to the distinction between a **control plane** and an **execution plane**.
|
||||
|
||||
---
|
||||
|
||||
### 5. Use events rather than shared mutable state across boundaries
|
||||
|
||||
Within one frontend, a Redux/Zustand/Pinia/etc. store can be useful.
|
||||
|
||||
Across independently evolving UI components, a giant shared store tends to become an implicit API.
|
||||
|
||||
Instead of:
|
||||
|
||||
```text
|
||||
component A
|
||||
↓
|
||||
global state object
|
||||
↑
|
||||
component B
|
||||
```
|
||||
|
||||
prefer:
|
||||
|
||||
```text
|
||||
CustomerSearch
|
||||
│
|
||||
│ customer-selected
|
||||
↓
|
||||
Application Shell
|
||||
│
|
||||
│ selectedCustomer=123
|
||||
↓
|
||||
CustomerEditor
|
||||
```
|
||||
|
||||
or an event/message mechanism where appropriate.
|
||||
|
||||
The semantic distinction is useful:
|
||||
|
||||
```text
|
||||
properties desired state/configuration
|
||||
events things that happened
|
||||
commands explicit requests
|
||||
queries information requests
|
||||
```
|
||||
|
||||
That simple vocabulary dramatically improves UI contracts.
|
||||
|
||||
---
|
||||
|
||||
### 6. Use isolation deliberately rather than universally
|
||||
|
||||
There is a spectrum:
|
||||
|
||||
```text
|
||||
Shared source/component
|
||||
↓
|
||||
npm package
|
||||
↓
|
||||
Web Component
|
||||
↓
|
||||
runtime remote module
|
||||
↓
|
||||
micro-frontend
|
||||
↓
|
||||
iframe
|
||||
```
|
||||
|
||||
Each step provides more autonomy/isolation, but also introduces more integration cost.
|
||||
|
||||
**Web Components** are particularly attractive for reusable framework-independent components because Shadow DOM can prevent CSS and DOM internals from colliding with their host application. :chatgpt-content-reference{index="1"}
|
||||
|
||||
For larger independently deployed application fragments, **Module Federation** is another established technique. Webpack explicitly describes its purpose as allowing separate builds to expose and consume modules at runtime, including the micro-frontend use case. :chatgpt-content-reference{index="2"}
|
||||
|
||||
I would not make either the universal solution.
|
||||
|
||||
A useful rule is:
|
||||
|
||||
> Use the weakest isolation mechanism that provides sufficient organizational and technical independence.
|
||||
|
||||
---
|
||||
|
||||
### 7. Avoid the "micro-frontends everywhere" trap
|
||||
|
||||
Micro-frontends are useful when there is genuinely independent ownership:
|
||||
|
||||
```text
|
||||
Team A Team B Team C
|
||||
Billing CRM Analytics
|
||||
release A release B release C
|
||||
\ | /
|
||||
Application Shell
|
||||
```
|
||||
|
||||
They are much less attractive when one team owns everything. You otherwise pay for:
|
||||
|
||||
- duplicate dependencies
|
||||
- runtime orchestration
|
||||
- version incompatibilities
|
||||
- inconsistent UX
|
||||
- authentication propagation
|
||||
- routing complexity
|
||||
- performance overhead
|
||||
- distributed debugging
|
||||
|
||||
without getting much organizational independence in return.
|
||||
|
||||
---
|
||||
|
||||
### 8. Make context explicit
|
||||
|
||||
One pattern I particularly recommend for complex platforms is a small, stable **host context**:
|
||||
|
||||
```ts
|
||||
interface UIHostContext {
|
||||
identity
|
||||
tenant
|
||||
locale
|
||||
theme
|
||||
permissions
|
||||
navigation
|
||||
notifications
|
||||
telemetry
|
||||
}
|
||||
```
|
||||
|
||||
But don't expose an enormous application object.
|
||||
|
||||
Instead expose capabilities:
|
||||
|
||||
```text
|
||||
context.identity.currentUser()
|
||||
context.navigation.open(...)
|
||||
context.notifications.publish(...)
|
||||
context.telemetry.record(...)
|
||||
```
|
||||
|
||||
This gives embedded components access to platform services without allowing them to become coupled to the entire host implementation.
|
||||
|
||||
---
|
||||
|
||||
### 9. Explicitly distinguish several kinds of compatibility
|
||||
|
||||
A UI component can be technically loadable and nevertheless incompatible.
|
||||
|
||||
I would track at least:
|
||||
|
||||
```text
|
||||
Protocol compatibility
|
||||
Can host and component communicate?
|
||||
|
||||
Semantic compatibility
|
||||
Do "customer-selected" and "customerId" mean the same thing?
|
||||
|
||||
Visual compatibility
|
||||
Does it fit the design system?
|
||||
|
||||
Interaction compatibility
|
||||
Keyboard, focus, navigation, modal behavior, etc.
|
||||
|
||||
Security compatibility
|
||||
Does it respect identity/authorization boundaries?
|
||||
|
||||
Lifecycle compatibility
|
||||
Can it mount, unmount, reconnect and upgrade safely?
|
||||
|
||||
Operational compatibility
|
||||
Can it be observed, debugged and degraded independently?
|
||||
```
|
||||
|
||||
This becomes important once components are reused across several applications.
|
||||
|
||||
---
|
||||
|
||||
## The architecture I would favour
|
||||
|
||||
For a modern platform with many interfaces, I would probably choose this combination:
|
||||
|
||||
```text
|
||||
UI PLATFORM
|
||||
|
||||
┌──────────┐
|
||||
│ App Shell │
|
||||
└────┬─────┘
|
||||
│
|
||||
┌────────────────┼────────────────┐
|
||||
│ │ │
|
||||
routing UI context capability
|
||||
layout identity registry
|
||||
navigation theme discovery
|
||||
locale
|
||||
│
|
||||
┌────────────┴────────────┐
|
||||
│ UI Component Contract │
|
||||
│ │
|
||||
│ props / events │
|
||||
│ commands / slots │
|
||||
│ lifecycle / metadata │
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌─────────────────────┼────────────────────┐
|
||||
│ │ │
|
||||
Native Web Component Microfrontend
|
||||
component boundary boundary
|
||||
│ │ │
|
||||
React React/Vue/etc independently
|
||||
Vue internally deployed
|
||||
Svelte
|
||||
```
|
||||
|
||||
Underneath all of this sits a shared:
|
||||
|
||||
```text
|
||||
Design Language
|
||||
↓
|
||||
Design Tokens
|
||||
↓
|
||||
Primitive Component Library
|
||||
↓
|
||||
Accessibility & interaction rules
|
||||
```
|
||||
|
||||
The browser platform is becoming an increasingly credible basis for that middle interoperability layer. Web Components provide native reusable elements; Shadow DOM supplies encapsulation; slots provide host/component composition; and scoped custom-element registries address one of the historical problems of large compositions—global custom-element naming collisions. :chatgpt-content-reference{index="3"}
|
||||
|
||||
### One additional concept I think is worth making explicit
|
||||
|
||||
Given the way you tend to approach interface architecture, I would distinguish between a **UI component** and an **Interface Capability**.
|
||||
|
||||
An Interface Capability would be:
|
||||
|
||||
> A self-describing unit of human-system interaction that exposes a stable semantic contract independently of its rendering implementation.
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
InterfaceCapability: DocumentViewer
|
||||
|
||||
provides:
|
||||
view-document
|
||||
browse-pages
|
||||
download-document
|
||||
|
||||
accepts:
|
||||
document-reference
|
||||
page-reference
|
||||
|
||||
emits:
|
||||
page-changed
|
||||
document-opened
|
||||
download-requested
|
||||
|
||||
requires:
|
||||
document.read
|
||||
|
||||
presentation:
|
||||
embeddable
|
||||
fullscreen
|
||||
|
||||
implementations:
|
||||
web-component
|
||||
react-component
|
||||
standalone-webapp
|
||||
```
|
||||
|
||||
That abstraction scales much better than thinking exclusively in terms of React components or micro-frontends. A component becomes **one implementation of an interface capability**.
|
||||
|
||||
And that in turn gives you a rather elegant architecture:
|
||||
|
||||
```text
|
||||
Interface Capability
|
||||
↓
|
||||
semantic contract
|
||||
↓
|
||||
one or more UI implementations
|
||||
↓
|
||||
composition/runtime adapter
|
||||
↓
|
||||
host application
|
||||
```
|
||||
|
||||
This is close to what I would regard as the current best-practice direction for a genuinely complex multi-interface platform: **design system below, semantic capability contracts in the middle, composition shell above, and implementation technology deliberately hidden behind the boundary.**
|
||||
53
research/candidates/CapabilityContractBoundary.md
Normal file
53
research/candidates/CapabilityContractBoundary.md
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
---
|
||||
title: Capability Contract Boundary
|
||||
status: draft
|
||||
maturity: hypothesis
|
||||
families: [composition, execution]
|
||||
scales: [L4]
|
||||
admission: research-candidate-only
|
||||
---
|
||||
|
||||
# Capability Contract Boundary
|
||||
|
||||
Context: a UI capability (e.g. a customer editor, a document viewer) is consumed by
|
||||
one or more independently evolving host applications, possibly across frameworks or
|
||||
teams. The host needs a stable way to configure, observe and command the capability
|
||||
without depending on its internal framework, state library or rendering technology.
|
||||
|
||||
Proposed solution: declare the capability's public surface as an explicit, versioned
|
||||
semantic contract — inputs/configuration, emitted events, invokable commands, and
|
||||
host-provided presentation slots — separately from whichever runtime-isolation
|
||||
mechanism (a plain package, a Custom Element, a Module Federation remote, a
|
||||
micro-frontend, an iframe) carries it. The contract is the thing consumers depend on
|
||||
and version against; the isolation mechanism is an implementation detail that can
|
||||
change without necessarily breaking the contract.
|
||||
|
||||
Result: hosts can swap or upgrade a capability's implementation without renegotiating
|
||||
its interface, and the interface can be reasoned about independently of deployment
|
||||
topology. Declaring a contract does not by itself provide runtime isolation, dependency
|
||||
negotiation or compatibility checking — those still come from whatever mechanism
|
||||
implements it (see Evidence). A contract with no enforcement is only documentation.
|
||||
|
||||
Evidence: [source review](../reviews/CapabilityContractSources.md) CC01–CC03 locates
|
||||
two real, independently documented substrate mechanisms — Custom Elements'
|
||||
attribute/lifecycle callbacks (CC01) and Module Federation's expose/consume module
|
||||
contract (CC02) — and establishes that neither defines a semantic capability contract
|
||||
itself (CC03); one would be authored on top of either. No known use of an explicit
|
||||
capability contract, as distinct from its substrate mechanisms, has been located.
|
||||
Prompted by a non-primary AI-chat lead that is explicitly not cited as evidence; see
|
||||
[SourceCatalog.md](../catalog/SourceCatalog.md).
|
||||
|
||||
Alternative: an ad hoc, framework-typed component API (e.g. React props/callbacks)
|
||||
when every consumer already shares the same framework and version, making a
|
||||
framework-neutral contract layer unnecessary overhead.
|
||||
|
||||
Proposed relations: [Independent Feature Boundary](IndependentFeatureBoundary.md)
|
||||
governs release/activation cadence and may carry a capability contract without being
|
||||
one; [Vertical Feature Slice](VerticalFeatureSlice.md) governs source-code grouping,
|
||||
a different concern. Neither entails this pattern nor is entailed by it.
|
||||
|
||||
Next test: pin one real Custom Element library and one real Module Federation
|
||||
example; compare what each actually enforces about a component's declared
|
||||
inputs/events/commands versus what a hand-authored capability-contract layer would
|
||||
need to add on top. All relations are research proposals; no canonical identity or
|
||||
admitted graph edges. The next test is planned, not executed.
|
||||
|
|
@ -223,3 +223,23 @@ records section locators, interpretations and limits. Documentary evidence only.
|
|||
|
||||
Six documents are four families, not six independent applications. No runtime,
|
||||
source-code verification, complete pattern recurrence or new maturity is established.
|
||||
|
||||
## Capability contract boundary — 2026-09-27
|
||||
|
||||
A pasted AI-chat exploration (`history/260927-ComplexWebAppUiComponents_chatgpt.txt`)
|
||||
was reviewed as a **leads document only, not a source**: it is unauthored, has
|
||||
unverifiable broken citation markers, and does not meet this catalog's primary-source
|
||||
bar. It is not assigned a SRC ID and carries no evidentiary weight. The two real specs
|
||||
it pointed to were read directly instead.
|
||||
|
||||
| ID | Source and edition | Family |
|
||||
| --- | --- | --- |
|
||||
| SRC-0046 | [MDN, Using custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements); living docs, accessed 2026-09-27, revision unknown | Web Components |
|
||||
| SRC-0047 | [webpack, Module Federation](https://webpack.js.org/concepts/module-federation/); living docs, accessed 2026-09-27, webpack 5, revision unknown | webpack |
|
||||
|
||||
[CC01–CC03](../reviews/CapabilityContractSources.md) locates Custom Elements'
|
||||
attribute/event/lifecycle mechanism and Module Federation's expose/consume module
|
||||
contract, and the boundary between them: neither spec defines a semantic
|
||||
props/events/commands/slots capability contract as a first-class concept. Documentary
|
||||
evidence only; no application/runtime execution. See
|
||||
[Capability Contract Boundary](../candidates/CapabilityContractBoundary.md) (CAND-0018).
|
||||
|
|
|
|||
|
|
@ -8,21 +8,21 @@ The baseline profiles are author-model assessments by Codex; they do not confer
|
|||
|
||||
## Current corpus
|
||||
|
||||
17 candidates: 17 hypothesis.
|
||||
18 candidates: 18 hypothesis.
|
||||
|
||||
| Evidence attached to a candidate | Candidates |
|
||||
| --- | ---: |
|
||||
| documentary | 17 |
|
||||
| documentary | 18 |
|
||||
| static-code | 7 |
|
||||
| runtime | 8 |
|
||||
|
||||
Categories overlap. Runtime includes authored fixtures and negative controls. Family labels group related evidence; they are not counts of independent applications.
|
||||
|
||||
Independent human profile reviews: 0/17. Full-contract independent-use counts unassessed: 17/17.
|
||||
Independent human profile reviews: 0/18. Full-contract independent-use counts unassessed: 18/18.
|
||||
|
||||
## Change since baseline
|
||||
|
||||
Baseline baseline-2026-09-26; source revision `f273a190f0e08b8cfe0bb7260d0e7d889f1c090a`. Added: 0; removed: 0; shared candidates with changed content: 3; changed evidence/review assessments: 17; maturity transitions: 0.
|
||||
Baseline baseline-2026-09-26; source revision `f273a190f0e08b8cfe0bb7260d0e7d889f1c090a`. Added: 1; removed: 0; shared candidates with changed content: 3; changed evidence/review assessments: 17; maturity transitions: 0.
|
||||
|
||||
The shared cohort is compared separately from additions. Changed text or evidence counts are not learning gains.
|
||||
|
||||
|
|
@ -391,6 +391,21 @@ Open limits: No upstream deployment or real team/release-independence validation
|
|||
|
||||
Superseded by: none recorded.
|
||||
|
||||
### CAND-0018 — Capability Contract Boundary
|
||||
|
||||
[CapabilityContractBoundary](../../research/candidates/CapabilityContractBoundary.md) · draft / hypothesis
|
||||
|
||||
Declare a UI capability's semantic surface separately from its runtime-isolation mechanism.
|
||||
|
||||
| Evidence | Family | Scope | Review |
|
||||
| --- | --- | --- | --- |
|
||||
| documentary | Web Components | CC01: Custom Elements observedAttributes/lifecycle callback mechanism, narrower than a full semantic contract. | [CapabilityContractSources](../../research/reviews/CapabilityContractSources.md) |
|
||||
| documentary | webpack | CC02: Module Federation expose/consume module and share-scope dependency-negotiation mechanism, one layer below any UI-facing contract. | [CapabilityContractSources](../../research/reviews/CapabilityContractSources.md) |
|
||||
|
||||
Open limits: No known use of an explicit capability contract, as distinct from its substrate mechanisms, has been located. Enforcement, versioning and compatibility checking are unverified; a contract with no tooling is only documentation. Only one family per substrate mechanism inspected; no independent recurrence.
|
||||
|
||||
Superseded by: none recorded.
|
||||
|
||||
## Recorded learning
|
||||
|
||||
### LEARN-0001 — What do pinned recovery implementations establish?
|
||||
|
|
|
|||
|
|
@ -743,6 +743,45 @@
|
|||
"Distributed atomicity, retention authorization and native-unload/crash behavior remain open."
|
||||
],
|
||||
"superseded_by": []
|
||||
},
|
||||
{
|
||||
"id": "CAND-0018",
|
||||
"path": "research/candidates/CapabilityContractBoundary.md",
|
||||
"title": "Capability Contract Boundary",
|
||||
"sha256": "a678f88e9b53d7273e29e3aea2d23f2297055253dcf4518444d3089fa6da4331",
|
||||
"status": "draft",
|
||||
"maturity": "hypothesis",
|
||||
"decision": "Declare a UI capability's semantic surface separately from its runtime-isolation mechanism.",
|
||||
"evidence": [
|
||||
{
|
||||
"kind": "documentary",
|
||||
"family": "Web Components",
|
||||
"ref": "research/reviews/CapabilityContractSources.md",
|
||||
"scope": "CC01: Custom Elements observedAttributes/lifecycle callback mechanism, narrower than a full semantic contract."
|
||||
},
|
||||
{
|
||||
"kind": "documentary",
|
||||
"family": "webpack",
|
||||
"ref": "research/reviews/CapabilityContractSources.md",
|
||||
"scope": "CC02: Module Federation expose/consume module and share-scope dependency-negotiation mechanism, one layer below any UI-facing contract."
|
||||
}
|
||||
],
|
||||
"independent_full_contract_uses": null,
|
||||
"review": {
|
||||
"assessed_at": "2026-09-27",
|
||||
"reviewer": "Codex",
|
||||
"role": "author-model",
|
||||
"independent_human": false,
|
||||
"last_substantive_review_date": "2026-09-27",
|
||||
"substantive_review_ref": "research/reviews/CapabilityContractSources.md",
|
||||
"substantive_review_scope": "Two real substrate specs read directly; the prompting AI-chat transcript is not evidence."
|
||||
},
|
||||
"gaps": [
|
||||
"No known use of an explicit capability contract, as distinct from its substrate mechanisms, has been located.",
|
||||
"Enforcement, versioning and compatibility checking are unverified; a contract with no tooling is only documentation.",
|
||||
"Only one family per substrate mechanism inspected; no independent recurrence."
|
||||
],
|
||||
"superseded_by": []
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
29
research/reviews/CapabilityContractSources.md
Normal file
29
research/reviews/CapabilityContractSources.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
# Capability contract boundary — real-spec source review
|
||||
|
||||
2026-09-27. Codex author-model review, documentary evidence only; no application
|
||||
or runtime execution. Prompted by a non-primary lead
|
||||
(`history/260927-ComplexWebAppUiComponents_chatgpt.txt`, a pasted AI-chat
|
||||
transcript with unverifiable, broken citation markers) that is **not** treated
|
||||
as a source or cited as evidence anywhere below — only the two real specs it
|
||||
pointed to were actually read. See [SourceCatalog.md](../catalog/SourceCatalog.md).
|
||||
|
||||
## Located claims
|
||||
|
||||
| Claim | Located text | Interpretation / limit |
|
||||
| --- | --- | --- |
|
||||
| CC01 — Custom Elements lifecycle contract | [MDN, Using custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements): a custom element class declares `static observedAttributes`, and the platform calls `connectedCallback()`, `disconnectedCallback()`, `adoptedCallback()` and `attributeChangedCallback(name, oldValue, newValue)` at defined lifecycle points. | This is a real, browser-native lifecycle/attribute-change notification mechanism. It is narrower than a full "capability contract": this specific page documents attributes and lifecycle callbacks, not a standardized way to declare *semantic* events, commands or slots for a component's public interface — those are separate platform features (custom events, `<slot>`) that this page does not cover in the sections read. |
|
||||
| CC02 — Module Federation's expose/consume contract | [webpack, Module Federation](https://webpack.js.org/concepts/module-federation/): a build acts as a "container" that exposes modules through a two-step contract (async load, then sync evaluate); other builds consume it as a "remote module." Shared modules are negotiated through a "share scope" with a `packageName`/`requiredVersion`, not bundled per build. | This is a real, documented mechanism for *code loading and dependency sharing* across independently built bundles. It says nothing about the shape of a UI component's semantic interface (props/events/commands) — Module Federation operates at the module-resolution layer, one layer below any UI-facing contract. |
|
||||
| CC03 — the two mechanisms are complementary, not equivalent | Neither CC01 nor CC02 defines a semantic "capability contract" (inputs/events/commands/slots/lifecycle as a declared, versioned interface) as a first-class platform or tool concept. | A semantic capability contract, if adopted, would need to be authored *on top of* one or both of these mechanisms (e.g., attributes/custom-events on a Custom Element, or an exposed module's function signature in Module Federation) — it is not something either spec hands you directly. This is the gap the reviewed lead's "Interface Capability" idea was pointing at, but the lead itself is not evidence that anyone has actually built or standardized it. |
|
||||
|
||||
## Disposition
|
||||
|
||||
Draft [Capability Contract Boundary](../candidates/CapabilityContractBoundary.md)
|
||||
(CAND-0018) as a new hypothesis, distinct from [Independent Feature Boundary](../candidates/IndependentFeatureBoundary.md)
|
||||
(release/activation cadence) and [Vertical Feature Slice](../candidates/VerticalFeatureSlice.md)
|
||||
(source-code grouping): this pattern concerns the *shape* of a UI capability's
|
||||
public semantic surface, independent of which runtime-isolation mechanism
|
||||
(package, Web Component, Module Federation remote, micro-frontend, iframe)
|
||||
implements it. Two documentary sources, one family each (Web Components,
|
||||
webpack); no independent known use of a capability contract itself is claimed —
|
||||
only that its two candidate substrates are real and independently documented.
|
||||
No canonical admission, no application/runtime evidence, no M1/M2 status change.
|
||||
|
|
@ -362,3 +362,20 @@ a returns review, and the workplan's rule against manufacturing cycles to reach
|
|||
that count still applies. A stale-navigation reproduction, if pursued, needs
|
||||
actual execution and is out of scope for the static-source protocol used here.
|
||||
T02/T03/T04 unchanged; the local authored navigation fixture remains paused.
|
||||
|
||||
## Capability Contract Boundary drafted from a screened lead — 2026-09-27
|
||||
|
||||
T01: `history/260927-ComplexWebAppUiComponents_chatgpt.txt`, a pasted AI-chat
|
||||
transcript on UI-integration architecture, was screened as a non-primary lead,
|
||||
not a source — it is unauthored and carries unverifiable citation markers, so
|
||||
it is not assigned a SRC ID and is not cited as evidence anywhere. Read the two
|
||||
real specs it pointed to instead: MDN Custom Elements (SRC-0046) and webpack
|
||||
Module Federation (SRC-0047). See [review](../research/reviews/CapabilityContractSources.md).
|
||||
|
||||
Drafted [Capability Contract Boundary](../research/candidates/CapabilityContractBoundary.md)
|
||||
(CAND-0018): declaring a UI capability's semantic surface (inputs/events/commands/
|
||||
slots) separately from whichever runtime-isolation mechanism carries it. Distinct
|
||||
from Independent Feature Boundary (release cadence) and Vertical Feature Slice
|
||||
(source grouping). Eighteen hypotheses now exist; no known use of an explicit
|
||||
capability contract located, no application/runtime evidence, no canonical
|
||||
admission or M1/M2 change.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue