ZAKON — CI Stub Type Declarations Contract

ZAKON — CI Stub Type Declarations Contract

Status: ACTIVE Created: 2026-07-28 Origin: Bilko MC #9616 — TypeScript gate failures after CI stub packages lacked declaration contracts. Applies to: Bilko, Drop, Tok, and any repo that substitutes internal packages with CI stub packages.

Rule

Every package directory under a CI stub root (ci/stubs/ or the repo's documented current equivalent such as Bilko tools/ci-stubs/) MUST contain:

1. package.json
2. index.d.ts
3. A types field in package.json pointing at the declaration file, normally "./index.d.ts"

Runtime-only stubs are not sufficient. TypeScript gates must see the same named export surface that application code imports.

Required Declaration Shape

The declaration file must declare every named export consumed by the repo. Use any where the stub intentionally avoids modelling runtime internals.

Minimal examples:

export declare const someExport: any
export type SomeType = any

If the real package has a default export and consumers import it, the stub declaration must include the default export too.

Enforcement

Repos with CI stubs must wire a deterministic check into at least one developer/CI gate:

npm run ci-stubs:types-contract

The check must fail when any stub package is missing index.d.ts, missing types, or points types to a missing file.

Acceptance Evidence

A task/PR touching CI stubs must show:

• Stub root path verified on disk.
• All stub package names found.
• index.d.ts exists for every stub package.
• package.json has a types field for every stub package.
• The contract check command exits 0.

Blockers

Block the task before push/dispatch if:

• Any stub package has only index.js.
• package.json lacks types.
• The types path points to a missing declaration file.
• The declaration file omits named exports imported by checked TypeScript code.

Related Standards

• ~/system/rules/zakon-lockfile-portability.md
• ~/system/rules/zakon-local-docker-build.md
• Bilko BUILD-BLUEPRINT.md §11 and §14