svelte-kit-vice/web/routes/active/get-started/versioning/+page.svelte

<script lang="ts">
	import CodeBlock from '../../_components/CodeBlock.svelte';
	import Callout from '../../_components/Callout.svelte';
	import PageNav from '../../_components/PageNav.svelte';

	const stableSurface = `// Fixed App core for the 1.0 line.
const App = createActiveApp();

App.logger;
App.bus;
App.timers;
App.orca;
App.prefs;
App.dispose();`;

	const scopedSurface = `// Core options (logger, timers, bus, orca, prefs) and schema-declared
// services are stable by slot name, but their option shapes may grow
// during 1.x if the change is additive.
createActiveApp({ prefs: { capabilities }, services: { /* ... */ } });

defineActiveLangs({ schema });
defineActiveFormat({});
defineActiveDom({});
defineActiveStorage({});
defineEngineHttp({});
defineActiveCache({});
defineEngineSium({});
defineActiveSession({ /* ... */ });
defineActiveConnections({ /* ... */ });
defineActiveAuth({ /* ... */ });
defineActivePerm({ /* ... */ });`;

	const deprecation = `/**
 * @deprecated Use setCurrency('auto') or clearCurrency() instead.
 * Deprecated in 1.0.3. Earliest removal: 2.0.0.
 */
function resetCurrency(): void {
    logger.warn('format.currency.deprecated.reset_currency', {
        context: { replacement: 'clearCurrency' }
    });
    clearCurrency();
}`;

	const experimental = `export const __EXPERIMENTAL_AUTH_WEBAUTHN = {
    createRegistrationOptions,
    verifyRegistration
};

// Experimental exports may change without the 1.x stability guarantee.
// They must be clearly named and documented as experimental.`;
</script>

<svelte:head>
	<title>Versioning — Active</title>
</svelte:head>

<article class="article">
	<header class="breadcrumbs">
		<a href="/active">Get Started</a>
		<span aria-hidden="true">/</span>
		<span>Versioning</span>
	</header>

	<h1>Versioning</h1>
	<p class="lead">
		Active is being hardened for <code>1.0</code>. The stable cut is a contract: public
		runtime shape, documented module boundaries and release checks must stop moving silently.
	</p>

	<h2>What 1.0 means</h2>
	<p>
		<code>1.0.x</code> is the line where application code can build against the ecosystem
		without reading every commit. The guarantee is focused: the fixed App core keeps its
		public shape, services are declared through stable schema slots, security-sensitive
		exported methods either work or are not exported, and breaking removals wait for a major
		version.
	</p>

	<Callout variant="info" title="Stable contract, explicit scope">
		<p>
			<code>1.0</code> means the documented runtime contract is stable. It does not require
			every possible product feature to exist: OAuth provider catalog, MFA, production
			WebAuthn, regulated workload readiness and npm distribution remain explicit future
			milestones unless they are documented as part of the release.
		</p>
	</Callout>

	<h2>Stable during 1.x</h2>
	<p>
		The fixed App core is the baseline contract: <code>Logger</code>, <code>Bus</code>,
		<code>Timers</code>, <code>Orca</code>, <code>Prefs</code> and <code>dispose()</code>.
		The service schema and preset behavior are covered under <code>src/arts/active-app/test</code>;
		changes should be additive unless they go through the deprecation process and wait for the
		next major.
	</p>
	<CodeBlock code={stableSurface} lang="ts" title="Fixed App core" />

	<table>
		<thead>
			<tr>
				<th>Stable item</th>
				<th>Guarantee</th>
				<th>Allowed in patch/minor</th>
			</tr>
		</thead>
		<tbody>
			<tr><td>Core property names</td><td>No silent removal or rename.</td><td>Additive core members only after docs/tests.</td></tr>
			<tr><td>Existing method names</td><td>No silent removal or semantic inversion.</td><td>Optional parameters and overloads.</td></tr>
			<tr><td>Error classes and guards</td><td>Keep type guards valid.</td><td>New error subclasses/codes.</td></tr>
			<tr><td>Constants for public strings</td><td>Names stay searchable and centralized.</td><td>New constants for new events/routes/methods.</td></tr>
			<tr><td>Logger contract</td><td>Modules depend on <code>$libs/logger.Logger</code>.</td><td>EngineLogger may add runtime helpers.</td></tr>
		</tbody>
	</table>

	<h2>Scoped factories</h2>
	<p>
		Service factories are stable entry points. Their child surfaces may grow during
		<code>1.x</code> when the change is additive, especially <code>Auth</code>,
		<code>Perm</code>, <code>Connections</code>, <code>Orca</code> and <code>Sium</code>.
	</p>
	<CodeBlock code={scopedSurface} lang="ts" title="Service-schema factories" />

	<p>
		Additive changes are allowed. Removing a method, changing a return shape, moving a method
		between client/server layers or making an optional option required needs deprecation first.
	</p>

	<h2>Deprecation policy</h2>
	<p>
		Deprecated stable APIs remain compatible through the <code>1.x</code> line. The deprecated
		path must have JSDoc, docs, tests, and a runtime warning only when the old path is actually
		used. Removal belongs to <code>2.0</code> unless the API was explicitly experimental.
	</p>
	<CodeBlock code={deprecation} lang="ts" title="Deprecation pattern" />

	<table>
		<thead>
			<tr>
				<th>Step</th>
				<th>Required action</th>
				<th>Why</th>
			</tr>
		</thead>
		<tbody>
			<tr><td>Mark</td><td>Add <code>@deprecated</code> JSDoc with replacement and earliest removal.</td><td>Editors and docs surface the migration.</td></tr>
			<tr><td>Warn</td><td>Emit a constant-backed warning when the old path is used.</td><td>Runtime users discover it without log spam.</td></tr>
			<tr><td>Keep</td><td>Maintain compatibility through the current major.</td><td>No silent breakage inside <code>1.x</code>.</td></tr>
			<tr><td>Test</td><td>Keep a regression test for old and new paths until removal.</td><td>Deprecation is behavior, not a comment.</td></tr>
			<tr><td>Remove</td><td>Remove only after the documented window and changelog entry.</td><td>Consumers can plan upgrades.</td></tr>
		</tbody>
	</table>

	<h2>Experimental APIs</h2>
	<p>
		If a feature is useful but not contract-ready, it must be exported under an explicit
		<code>__EXPERIMENTAL_*</code> name. Experimental APIs are not covered by the
		<code>1.x</code> stability guarantee.
	</p>
	<CodeBlock code={experimental} lang="ts" title="Experimental namespace" />

	<Callout variant="warn" title="No hidden experiments">
		<p>
			Do not ship unstable APIs under normal names. A method that exists in the stable surface
			must work, be documented, be tested, or be removed before release.
		</p>
	</Callout>

	<h2>Release checklist</h2>
	<ul>
		<li>Run <code>npm run test:all</code> before tagging.</li>
		<li>Run <code>npm run check</code>, <code>npm test</code>, <code>npm run build</code>, <code>npm run test:static</code> or <code>npm run test:bundle</code> separately only when isolating a failing step.</li>
		<li>Update <code>CHANGELOG.md</code> with added, changed, fixed and security notes.</li>
		<li>Update module README and <code>/active/docs/&lt;module&gt;</code> for public API changes.</li>
		<li>Update public-surface tests when adding stable members.</li>
		<li>Keep <code>createActiveApp(&#123;&#125;)</code> under the bundle smoke budget unless the budget is intentionally raised in docs and CI.</li>
		<li>Keep lint debt from growing even while full-repo lint cleanup remains open.</li>
	</ul>

	<PageNav />
</article>

<style>
	.breadcrumbs {
		display: flex;
		align-items: center;
		gap: 0.4rem;
		font-size: 0.8125rem;
		color: var(--c-fg-subtle);
		margin-bottom: 1rem;
	}

	.breadcrumbs a {
		color: var(--c-fg-muted);
	}
</style>