OSS-first docs
These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.
Deterministic codegen
Regenerate code from contracts without breaking existing functionality or losing customizations.
Regeneration Challenges
- Generated code conflicts with manual changes
- Regeneration loses custom business logic
- Teams avoid regeneration after customization
- Code migration between versions is risky
Deterministic Solutions
- Clear separation of generated vs hand-written code
- Incremental regeneration with conflict detection
- Protected zones for custom logic
- Automatic migration paths
Protected Zones
Separate generated code from hand-written business logic with clear boundaries.
src/handlers/user-handlers.ts
// Hand-written business logic (protected from regeneration)
export class UserService {
async createUser(input: CreateUserInput): Promise<CreateUserOutput> {
// Custom validation and business rules
if (await this.emailExists(input.email)) {
throw new Error('Email already exists');
}
// Persistence logic
const user = await this.repository.create({
email: input.email,
name: input.name,
password: await this.hashPassword(input.password),
});
return {
id: user.id,
email: user.email,
name: user.name,
createdAt: user.createdAt.toISOString(),
};
}
private async emailExists(email: string): Promise<boolean> {
// Custom business validation
return !!(await this.repository.findByEmail(email));
}
}
// Generated handler wrapper (can be regenerated safely)
export const createUserHandler = wrapOperationHandler(
UserService.prototype.createUser,
{
serviceName: 'UserService',
operationName: 'createUser',
errorMapper: mapToStandardErrors,
}
);Incremental Regeneration
Regenerate only what changed while preserving custom logic.
incremental-regen
contractspec generate \
--incremental \
--preserve-zones ./src/handlers/*.ts \
--input ./src/contracts/ \
--output ./generated/Conflict Detection
Automatically detect and report conflicts during regeneration.
check-conflicts
contractspec generate \
--check-conflicts \
--report-conflicts ./conflicts.jsonOSS docsStart with OSS. Adopt Studio when you want the operating layer.
Why ContractSpec
Keep educational and comparison content reachable without letting it define the primary OSS learning path.