Skip to content

Commit b03e0f3

Browse files
claude[bot]claude
andauthored
docs: link the four sitemap-only orphan pages back into the site (#13780)
Three doc pages had zero inbound links from any other page's prose: `/docs/kernel/contracts/auth-service`, `/docs/kernel/contracts/cache-service` and `/docs/protocol/backward-compatibility`. The fourth page named in the report, `/docs/concepts/metadata-driven`, acquired an inbound link from `getting-started/glossary` on 2026-08-26 and is no longer orphaned. Structural: the Contract Catalog on `kernel/contracts/index.mdx` listed all five contracts that have their own page as plain text, so the section index linked none of its children. Each of the five now links to its page. Topical, so the link is one a reader has a reason to follow: - `permissions/authentication` -> the `IAuthService` contract, where the page already talks about a service that does not implement `handleRequest` - `plugins/packages` -> the `ICacheService` contract, from the sentence that names the contract the cache service sits behind - `protocol/index` and `upgrading` -> the Backward Compatibility Policy, which is what decides what a major may change Face touched: body prose links only. No frontmatter, no headings, no `meta.json` (all four pages were already listed in theirs). Co-authored-by: Claude <noreply@anthropic.com>
1 parent 36d2878 commit b03e0f3

5 files changed

Lines changed: 16 additions & 7 deletions

File tree

content/docs/kernel/contracts/index.mdx

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,25 +29,25 @@ Service contracts are **TypeScript interfaces** that define the boundaries betwe
2929

3030
| Contract | Interface | Description |
3131
|:---|:---|:---|
32-
| Data Engine | `IDataEngine` | Core data persistence — CRUD, queries, aggregations, transactions |
33-
| Metadata Service | `IMetadataService` | Object and field definition management, schema registry |
32+
| [Data Engine](/docs/kernel/contracts/data-engine) | `IDataEngine` | Core data persistence — CRUD, queries, aggregations, transactions |
33+
| [Metadata Service](/docs/kernel/contracts/metadata-service) | `IMetadataService` | Object and field definition management, schema registry |
3434
| Search Service | `ISearchService` | Full-text search indexing and querying |
3535
| Data Driver | `IDataDriver` | Low-level database adapter (SQL, NoSQL, API) |
3636

3737
### Authentication & Security Contracts
3838

3939
| Contract | Interface | Description |
4040
|:---|:---|:---|
41-
| Auth Service | `IAuthService` | Authentication — login, verify, logout, session management |
41+
| [Auth Service](/docs/kernel/contracts/auth-service) | `IAuthService` | Authentication — login, verify, logout, session management |
4242
| Security Service | `ISecurityService` | Query surface for access decisions — row-level read scope, readable-field projection, effective permission sets, access explanation |
4343
| Sharing Service | `ISharingService` | Record sharing rules and access grants |
4444

4545
### Storage & Caching Contracts
4646

4747
| Contract | Interface | Description |
4848
|:---|:---|:---|
49-
| Storage Service | `IStorageService` | File upload, download, and management |
50-
| Cache Service | `ICacheService` | Key-value caching with TTL support |
49+
| [Storage Service](/docs/kernel/contracts/storage-service) | `IStorageService` | File upload, download, and management |
50+
| [Cache Service](/docs/kernel/contracts/cache-service) | `ICacheService` | Key-value caching with TTL support |
5151

5252
### System Contracts
5353

content/docs/permissions/authentication.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1276,7 +1276,7 @@ The dispatcher used to carry a **mock fallback**: with no auth service in the sl
12761276

12771277
It was never an authentication bypass — no session store backed that token, so the identity path still resolved anonymous and anonymous data access was still denied. The problem was that it told the client it had authenticated someone when it had not, while discovery simultaneously reported `auth: unavailable` and advertised no `routes.auth`. A capability the runtime does not have must not be advertised by pretending to serve it (ADR-0076 D12, ADR-0115).
12781278

1279-
A service registered in the slot but not implementing the contract's `handleRequest` takes the same 501.
1279+
A service registered in the slot but not implementing [`handleRequest` from the `IAuthService` contract](/docs/kernel/contracts/auth-service) takes the same 501.
12801280

12811281
**If you were relying on the mock** for a browser-only or MSW build: mock at the HTTP client layer, or with an MSW handler in your own test setup, which is what the console does. Load `AuthPlugin` (it needs no HTTP server — see above) and the real service answers instead.
12821282

content/docs/plugins/packages.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -228,7 +228,7 @@ All services implement contracts from `@objectstack/spec/contracts` and are kern
228228

229229
### @objectstack/service-cache
230230

231-
**Cache Service** — In-memory caching behind the `ICacheService` contract.
231+
**Cache Service** — In-memory caching behind the [`ICacheService` contract](/docs/kernel/contracts/cache-service).
232232

233233
- **Adapters**: Memory (the only working adapter). `RedisCacheAdapter` is a **skeleton** — every method throws `not yet implemented`, and `CacheServicePlugin({ adapter: 'redis' })` refuses to start. For a real distributed cache, register your own `ICacheService` via `ctx.registerService('cache', impl)`.
234234
- **Features**: `get` / `set` / `delete` / `has` / `clear` / `stats`, per-entry TTL, `maxSize` eviction, lookup & write metrics

content/docs/protocol/index.mdx

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,11 @@ The ObjectStack Protocol defines three interconnected layers that together descr
1313
<Card icon={<Cpu />} title="Kernel: System Protocol" href="/docs/protocol/kernel" description="Runtime lifecycle, HTTP/realtime protocols, plugins, configuration, and i18n." />
1414
</Cards>
1515

16+
All three layers move under one compatibility contract: which edits a MINOR may make, how long a
17+
deprecated property survives before it can be removed, and which `@objectstack/spec` exports are
18+
guaranteed stable within a MAJOR — see the [Backward Compatibility
19+
Policy](/docs/protocol/backward-compatibility).
20+
1621
## Design Principles
1722

1823
- **Zod-First** — All schemas are defined in Zod for runtime validation and TypeScript inference.

content/docs/upgrading.mdx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,10 @@ Curated notes for v10 and v11 were never backfilled; consult the per-package
206206
`CHANGELOG.md` files for those two. The [release notes
207207
overview](/docs/releases) summarizes what each major changed.
208208

209+
What a major is *allowed* to change in the first place — which edits count as breaking,
210+
and the deprecation window a property must sit through before it can be removed — is the
211+
[Backward Compatibility Policy](/docs/protocol/backward-compatibility).
212+
209213
## Not this page
210214

211215
**Upgrading an installed package** — a template app or a third-party package

0 commit comments

Comments
 (0)