@forgezero/access 0.1.14 → 0.1.15

package/README.md

@@ -36,6 +36,7 @@ These are supported consumer entry points, not every internal module shipped for
 | public entry | short description | runtime | details |
 |---|---|---|---|
 | @forgezero/access | Declare routes, factors and policies as orthogonal lists; authorise against them. | portable | [Reference + usage](#forgezero-access) |
+| @forgezero/access/schema | Dependency-free JSON Schema builders, inference, Pick/Omit/Extend composition and runtime boundary parsing so request and response types have one source. | portable | [Reference + usage](#forgezero-access-schema) |
 | @forgezero/access/conditions | The twelve guards every project writes into `before`, each with the status its refusal deserves. | portable | [Reference + usage](#forgezero-access-conditions) |
 | @forgezero/access/effects | Audit, emit, meter, invalidate and notify — what happens after a request is decided, never failing it. | portable | [Reference + usage](#forgezero-access-effects) |
 | @forgezero/access/security | Constant-time comparison, CSPRNG tokens, HMAC, HKDF, AES-GCM sealing and redaction. Web Crypto only. | portable | [Reference + usage](#forgezero-access-security) |
@@ -50,6 +51,7 @@ These are supported consumer entry points, not every internal module shipped for
 | @forgezero/access/principal-session | Short-lived scope-bound delegated-principal sessions with sliding and absolute expiry. | portable | [Reference + usage](#forgezero-access-principal-session) |
 | @forgezero/access/authenticator | Authentication-source contracts for adding identity mechanisms without changing route policy. | portable | [Reference + usage](#forgezero-access-authenticator) |
 | @forgezero/access/ceremony-modes | Named security-ceremony modes and their session/action fulfilment semantics. | portable | [Reference + usage](#forgezero-access-ceremony-modes) |
+| @forgezero/access/vault | Runtime-validated Service, Platform Authority and exact Deployment Vault coordinates and bindings. | portable | [Reference + usage](#forgezero-access-vault) |
 
 ## Commands
 
@@ -87,6 +89,29 @@ export const routes = defineRoutes({
 });
 ```
 
+<a id="forgezero-access-schema"></a>
+## @forgezero/access/schema
+
+Dependency-free JSON Schema builders, inference, Pick/Omit/Extend composition and runtime boundary parsing so request and response types have one source. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
+
+```text
+import {
+  extend,
+} from '@forgezero/access/schema';
+```
+
+## @forgezero/access/schema — Use this entry point
+
+This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.
+
+```text
+import {
+  extend,
+} from '@forgezero/access/schema';
+
+export const selectedCapability = extend;
+```
+
 <a id="forgezero-access-conditions"></a>
 ## @forgezero/access/conditions
 
@@ -409,6 +434,37 @@ import {
 export const selectedCapability = MAX_CUSTODIANS;
 ```
 
+<a id="forgezero-access-vault"></a>
+## @forgezero/access/vault
+
+Runtime-validated Service, Platform Authority and exact Deployment Vault coordinates and bindings. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
+
+```text
+import {
+  DeploymentCredentialPurposeSchema,
+} from '@forgezero/access/vault';
+```
+
+## @forgezero/access/vault — Declare an exact Vault domain and deployment binding
+
+Service records, platform authority, and deployment inputs are distinct runtime-validated coordinates. Deployment credentials always name their exact deployment and environment.
+
+```text
+import {
+  parseDeploymentVaultBinding,
+} from '@forgezero/access/vault';
+
+const binding = parseDeploymentVaultBinding({
+  vaultDomain: 'deployment',
+  realmKey: 'platform',
+  projectKey: 'fz',
+  deploymentKey: 'platform-api',
+  environment: 'development',
+  entryKey: 'cloudflare-management'
+});
+if (!binding) throw new Error('Invalid deployment Vault binding');
+```
+
 ## 1. Install
 
 Zero runtime dependencies. The core is fetch types plus plain JSON Schema, so it runs on Bun, Node 18+, Cloudflare Workers, Deno and every edge runtime.

package/dist/conditions.js

@@ -59,14 +59,42 @@ function defineFactors(factors) {
   }
   return factors;
 }
+var ROUTE_LIFECYCLE_STATES = ["active", "deprecated", "retired"];
 function page(label, options = {}) {
-  return { kind: "page", label, accessGroup: "default", ...options };
+  return {
+    kind: "page",
+    label,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, accessGroup: "default", ...options };
+  return {
+    kind: "action",
+    label,
+    method,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    const lifecycle = route.lifecycle;
+    if (!Number.isSafeInteger(lifecycle.version) || lifecycle.version < 1) {
+      throw new AccessError("ROUTE_VERSION_INVALID", `"${key}": route version must be a positive integer.`);
+    }
+    const validTimestamp = (value) => Number.isFinite(Date.parse(value));
+    if (lifecycle.introducedAt !== "initial" && !validTimestamp(lifecycle.introducedAt)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": introducedAt must be an ISO timestamp or initial.`);
+    }
+    if (lifecycle.status === "deprecated" && (!validTimestamp(lifecycle.deprecatedAt) || !validTimestamp(lifecycle.expiresAt) || Date.parse(lifecycle.deprecatedAt) > Date.parse(lifecycle.expiresAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": deprecated route lifecycle is invalid.`);
+    }
+    if (lifecycle.status === "retired" && (!validTimestamp(lifecycle.retiredAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": retired route lifecycle is invalid.`);
+    }
     if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
       throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
     }
@@ -224,6 +252,10 @@ function defineAccessControl(config) {
       const route = config.routes[key];
       if (!route)
         return false;
+      if (route.lifecycle?.status === "retired")
+        return false;
+      if (route.lifecycle?.status === "deprecated" && Date.parse(context?.now ?? new Date().toISOString()) >= Date.parse(route.lifecycle.expiresAt))
+        return false;
       if (route.feature && !features.includes(route.feature))
         return false;
       if (context?.stage && route.stages && !route.stages.includes(context.stage))
@@ -275,7 +307,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.14";
+var VERSION = "0.1.15";
 
 // src/conditions.ts
 function define(condition, routes, refusals, run) {

package/dist/effects.js

@@ -59,14 +59,42 @@ function defineFactors(factors) {
   }
   return factors;
 }
+var ROUTE_LIFECYCLE_STATES = ["active", "deprecated", "retired"];
 function page(label, options = {}) {
-  return { kind: "page", label, accessGroup: "default", ...options };
+  return {
+    kind: "page",
+    label,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, accessGroup: "default", ...options };
+  return {
+    kind: "action",
+    label,
+    method,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    const lifecycle = route.lifecycle;
+    if (!Number.isSafeInteger(lifecycle.version) || lifecycle.version < 1) {
+      throw new AccessError("ROUTE_VERSION_INVALID", `"${key}": route version must be a positive integer.`);
+    }
+    const validTimestamp = (value) => Number.isFinite(Date.parse(value));
+    if (lifecycle.introducedAt !== "initial" && !validTimestamp(lifecycle.introducedAt)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": introducedAt must be an ISO timestamp or initial.`);
+    }
+    if (lifecycle.status === "deprecated" && (!validTimestamp(lifecycle.deprecatedAt) || !validTimestamp(lifecycle.expiresAt) || Date.parse(lifecycle.deprecatedAt) > Date.parse(lifecycle.expiresAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": deprecated route lifecycle is invalid.`);
+    }
+    if (lifecycle.status === "retired" && (!validTimestamp(lifecycle.retiredAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": retired route lifecycle is invalid.`);
+    }
     if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
       throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
     }
@@ -224,6 +252,10 @@ function defineAccessControl(config) {
       const route = config.routes[key];
       if (!route)
         return false;
+      if (route.lifecycle?.status === "retired")
+        return false;
+      if (route.lifecycle?.status === "deprecated" && Date.parse(context?.now ?? new Date().toISOString()) >= Date.parse(route.lifecycle.expiresAt))
+        return false;
       if (route.feature && !features.includes(route.feature))
         return false;
       if (context?.stage && route.stages && !route.stages.includes(context.stage))
@@ -275,7 +307,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.14";
+var VERSION = "0.1.15";
 
 // src/security.ts
 var HEX = Array.from({ length: 256 }, (_, index) => index.toString(16).padStart(2, "0"));

package/dist/elysia.js

@@ -59,14 +59,42 @@ function defineFactors(factors) {
   }
   return factors;
 }
+var ROUTE_LIFECYCLE_STATES = ["active", "deprecated", "retired"];
 function page(label, options = {}) {
-  return { kind: "page", label, accessGroup: "default", ...options };
+  return {
+    kind: "page",
+    label,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, accessGroup: "default", ...options };
+  return {
+    kind: "action",
+    label,
+    method,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    const lifecycle = route.lifecycle;
+    if (!Number.isSafeInteger(lifecycle.version) || lifecycle.version < 1) {
+      throw new AccessError("ROUTE_VERSION_INVALID", `"${key}": route version must be a positive integer.`);
+    }
+    const validTimestamp = (value) => Number.isFinite(Date.parse(value));
+    if (lifecycle.introducedAt !== "initial" && !validTimestamp(lifecycle.introducedAt)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": introducedAt must be an ISO timestamp or initial.`);
+    }
+    if (lifecycle.status === "deprecated" && (!validTimestamp(lifecycle.deprecatedAt) || !validTimestamp(lifecycle.expiresAt) || Date.parse(lifecycle.deprecatedAt) > Date.parse(lifecycle.expiresAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": deprecated route lifecycle is invalid.`);
+    }
+    if (lifecycle.status === "retired" && (!validTimestamp(lifecycle.retiredAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": retired route lifecycle is invalid.`);
+    }
     if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
       throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
     }
@@ -224,6 +252,10 @@ function defineAccessControl(config) {
       const route = config.routes[key];
       if (!route)
         return false;
+      if (route.lifecycle?.status === "retired")
+        return false;
+      if (route.lifecycle?.status === "deprecated" && Date.parse(context?.now ?? new Date().toISOString()) >= Date.parse(route.lifecycle.expiresAt))
+        return false;
       if (route.feature && !features.includes(route.feature))
         return false;
       if (context?.stage && route.stages && !route.stages.includes(context.stage))
@@ -275,7 +307,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.14";
+var VERSION = "0.1.15";
 
 // src/pipeline.ts
 function defineHandlers(routes, handlers) {

package/dist/fetch.js

@@ -59,14 +59,42 @@ function defineFactors(factors) {
   }
   return factors;
 }
+var ROUTE_LIFECYCLE_STATES = ["active", "deprecated", "retired"];
 function page(label, options = {}) {
-  return { kind: "page", label, accessGroup: "default", ...options };
+  return {
+    kind: "page",
+    label,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, accessGroup: "default", ...options };
+  return {
+    kind: "action",
+    label,
+    method,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    const lifecycle = route.lifecycle;
+    if (!Number.isSafeInteger(lifecycle.version) || lifecycle.version < 1) {
+      throw new AccessError("ROUTE_VERSION_INVALID", `"${key}": route version must be a positive integer.`);
+    }
+    const validTimestamp = (value) => Number.isFinite(Date.parse(value));
+    if (lifecycle.introducedAt !== "initial" && !validTimestamp(lifecycle.introducedAt)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": introducedAt must be an ISO timestamp or initial.`);
+    }
+    if (lifecycle.status === "deprecated" && (!validTimestamp(lifecycle.deprecatedAt) || !validTimestamp(lifecycle.expiresAt) || Date.parse(lifecycle.deprecatedAt) > Date.parse(lifecycle.expiresAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": deprecated route lifecycle is invalid.`);
+    }
+    if (lifecycle.status === "retired" && (!validTimestamp(lifecycle.retiredAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": retired route lifecycle is invalid.`);
+    }
     if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
       throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
     }
@@ -224,6 +252,10 @@ function defineAccessControl(config) {
       const route = config.routes[key];
       if (!route)
         return false;
+      if (route.lifecycle?.status === "retired")
+        return false;
+      if (route.lifecycle?.status === "deprecated" && Date.parse(context?.now ?? new Date().toISOString()) >= Date.parse(route.lifecycle.expiresAt))
+        return false;
       if (route.feature && !features.includes(route.feature))
         return false;
       if (context?.stage && route.stages && !route.stages.includes(context.stage))
@@ -275,7 +307,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.14";
+var VERSION = "0.1.15";
 
 // src/pipeline.ts
 function defineHandlers(routes, handlers) {

package/dist/header.js

@@ -59,14 +59,42 @@ function defineFactors(factors) {
   }
   return factors;
 }
+var ROUTE_LIFECYCLE_STATES = ["active", "deprecated", "retired"];
 function page(label, options = {}) {
-  return { kind: "page", label, accessGroup: "default", ...options };
+  return {
+    kind: "page",
+    label,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, accessGroup: "default", ...options };
+  return {
+    kind: "action",
+    label,
+    method,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    const lifecycle = route.lifecycle;
+    if (!Number.isSafeInteger(lifecycle.version) || lifecycle.version < 1) {
+      throw new AccessError("ROUTE_VERSION_INVALID", `"${key}": route version must be a positive integer.`);
+    }
+    const validTimestamp = (value) => Number.isFinite(Date.parse(value));
+    if (lifecycle.introducedAt !== "initial" && !validTimestamp(lifecycle.introducedAt)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": introducedAt must be an ISO timestamp or initial.`);
+    }
+    if (lifecycle.status === "deprecated" && (!validTimestamp(lifecycle.deprecatedAt) || !validTimestamp(lifecycle.expiresAt) || Date.parse(lifecycle.deprecatedAt) > Date.parse(lifecycle.expiresAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": deprecated route lifecycle is invalid.`);
+    }
+    if (lifecycle.status === "retired" && (!validTimestamp(lifecycle.retiredAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": retired route lifecycle is invalid.`);
+    }
     if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
       throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
     }
@@ -224,6 +252,10 @@ function defineAccessControl(config) {
       const route = config.routes[key];
       if (!route)
         return false;
+      if (route.lifecycle?.status === "retired")
+        return false;
+      if (route.lifecycle?.status === "deprecated" && Date.parse(context?.now ?? new Date().toISOString()) >= Date.parse(route.lifecycle.expiresAt))
+        return false;
       if (route.feature && !features.includes(route.feature))
         return false;
       if (context?.stage && route.stages && !route.stages.includes(context.stage))
@@ -275,7 +307,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.14";
+var VERSION = "0.1.15";
 
 // src/principal.ts
 var ATOM = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,255}$/;

package/dist/index.d.ts

@@ -127,8 +127,35 @@ export interface RouteContract {
      */
     response?: Record<number, unknown>;
 }
+export declare const ROUTE_LIFECYCLE_STATES: readonly ["active", "deprecated", "retired"];
+export type RouteLifecycleState = (typeof ROUTE_LIFECYCLE_STATES)[number];
+/**
+ * Lifecycle of one exact public route version. Retired or expired versions are
+ * absent (404), so old code is neither compiled as an active fallback nor
+ * accidentally kept reachable forever.
+ */
+export type RouteVersionLifecycle = Readonly<{
+    version: number;
+    status: 'active';
+    introducedAt: string;
+}> | Readonly<{
+    version: number;
+    status: 'deprecated';
+    introducedAt: string;
+    deprecatedAt: string;
+    expiresAt: string;
+    replacement: string;
+}> | Readonly<{
+    version: number;
+    status: 'retired';
+    introducedAt: string;
+    retiredAt: string;
+    replacement?: string;
+}>;
 export interface RouteBase extends RouteContract {
     label: string;
+    /** Exact API/page version and its support window. */
+    lifecycle: RouteVersionLifecycle;
     /** Open host vocabulary used to scope delegated role assignments. */
     accessGroup: string;
     /** Disabled feature → 404, never 403. A 403 confirms the route exists. */
@@ -317,6 +344,7 @@ export interface AccessControl<R extends RouteRegistry> {
     exists(key: string, context?: {
         stage?: string;
         realm?: string;
+        now?: string;
     }): boolean;
     sessionPolicyFor(key: string): SessionPolicy<string> | undefined;
     actionPolicyFor(key: string): ActionPolicy<string> | undefined;
@@ -379,4 +407,4 @@ export declare function impactOfDisabling<R extends RouteRegistry>(access: Acces
     available: number;
     required: number;
 }[];
-export declare const VERSION = "0.1.14";
+export declare const VERSION = "0.1.15";

package/dist/index.js

@@ -59,14 +59,42 @@ function defineFactors(factors) {
   }
   return factors;
 }
+var ROUTE_LIFECYCLE_STATES = ["active", "deprecated", "retired"];
 function page(label, options = {}) {
-  return { kind: "page", label, accessGroup: "default", ...options };
+  return {
+    kind: "page",
+    label,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, accessGroup: "default", ...options };
+  return {
+    kind: "action",
+    label,
+    method,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    const lifecycle = route.lifecycle;
+    if (!Number.isSafeInteger(lifecycle.version) || lifecycle.version < 1) {
+      throw new AccessError("ROUTE_VERSION_INVALID", `"${key}": route version must be a positive integer.`);
+    }
+    const validTimestamp = (value) => Number.isFinite(Date.parse(value));
+    if (lifecycle.introducedAt !== "initial" && !validTimestamp(lifecycle.introducedAt)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": introducedAt must be an ISO timestamp or initial.`);
+    }
+    if (lifecycle.status === "deprecated" && (!validTimestamp(lifecycle.deprecatedAt) || !validTimestamp(lifecycle.expiresAt) || Date.parse(lifecycle.deprecatedAt) > Date.parse(lifecycle.expiresAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": deprecated route lifecycle is invalid.`);
+    }
+    if (lifecycle.status === "retired" && (!validTimestamp(lifecycle.retiredAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": retired route lifecycle is invalid.`);
+    }
     if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
       throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
     }
@@ -224,6 +252,10 @@ function defineAccessControl(config) {
       const route = config.routes[key];
       if (!route)
         return false;
+      if (route.lifecycle?.status === "retired")
+        return false;
+      if (route.lifecycle?.status === "deprecated" && Date.parse(context?.now ?? new Date().toISOString()) >= Date.parse(route.lifecycle.expiresAt))
+        return false;
       if (route.feature && !features.includes(route.feature))
         return false;
       if (context?.stage && route.stages && !route.stages.includes(context.stage))
@@ -275,7 +307,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.14";
+var VERSION = "0.1.15";
 export {
   stemOf,
   resolveActionFactors,
@@ -297,5 +329,6 @@ export {
   Settled,
   SCHEMA_VERSION,
   Refusal,
+  ROUTE_LIFECYCLE_STATES,
   AccessError
 };

package/dist/pipeline.js

@@ -59,14 +59,42 @@ function defineFactors(factors) {
   }
   return factors;
 }
+var ROUTE_LIFECYCLE_STATES = ["active", "deprecated", "retired"];
 function page(label, options = {}) {
-  return { kind: "page", label, accessGroup: "default", ...options };
+  return {
+    kind: "page",
+    label,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, accessGroup: "default", ...options };
+  return {
+    kind: "action",
+    label,
+    method,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    const lifecycle = route.lifecycle;
+    if (!Number.isSafeInteger(lifecycle.version) || lifecycle.version < 1) {
+      throw new AccessError("ROUTE_VERSION_INVALID", `"${key}": route version must be a positive integer.`);
+    }
+    const validTimestamp = (value) => Number.isFinite(Date.parse(value));
+    if (lifecycle.introducedAt !== "initial" && !validTimestamp(lifecycle.introducedAt)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": introducedAt must be an ISO timestamp or initial.`);
+    }
+    if (lifecycle.status === "deprecated" && (!validTimestamp(lifecycle.deprecatedAt) || !validTimestamp(lifecycle.expiresAt) || Date.parse(lifecycle.deprecatedAt) > Date.parse(lifecycle.expiresAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": deprecated route lifecycle is invalid.`);
+    }
+    if (lifecycle.status === "retired" && (!validTimestamp(lifecycle.retiredAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": retired route lifecycle is invalid.`);
+    }
     if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
       throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
     }
@@ -224,6 +252,10 @@ function defineAccessControl(config) {
       const route = config.routes[key];
       if (!route)
         return false;
+      if (route.lifecycle?.status === "retired")
+        return false;
+      if (route.lifecycle?.status === "deprecated" && Date.parse(context?.now ?? new Date().toISOString()) >= Date.parse(route.lifecycle.expiresAt))
+        return false;
       if (route.feature && !features.includes(route.feature))
         return false;
       if (context?.stage && route.stages && !route.stages.includes(context.stage))
@@ -275,7 +307,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.14";
+var VERSION = "0.1.15";
 
 // src/pipeline.ts
 function defineHandlers(routes, handlers) {

package/dist/principal-session.js

@@ -59,14 +59,42 @@ function defineFactors(factors) {
   }
   return factors;
 }
+var ROUTE_LIFECYCLE_STATES = ["active", "deprecated", "retired"];
 function page(label, options = {}) {
-  return { kind: "page", label, accessGroup: "default", ...options };
+  return {
+    kind: "page",
+    label,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, accessGroup: "default", ...options };
+  return {
+    kind: "action",
+    label,
+    method,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    const lifecycle = route.lifecycle;
+    if (!Number.isSafeInteger(lifecycle.version) || lifecycle.version < 1) {
+      throw new AccessError("ROUTE_VERSION_INVALID", `"${key}": route version must be a positive integer.`);
+    }
+    const validTimestamp = (value) => Number.isFinite(Date.parse(value));
+    if (lifecycle.introducedAt !== "initial" && !validTimestamp(lifecycle.introducedAt)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": introducedAt must be an ISO timestamp or initial.`);
+    }
+    if (lifecycle.status === "deprecated" && (!validTimestamp(lifecycle.deprecatedAt) || !validTimestamp(lifecycle.expiresAt) || Date.parse(lifecycle.deprecatedAt) > Date.parse(lifecycle.expiresAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": deprecated route lifecycle is invalid.`);
+    }
+    if (lifecycle.status === "retired" && (!validTimestamp(lifecycle.retiredAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": retired route lifecycle is invalid.`);
+    }
     if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
       throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
     }
@@ -224,6 +252,10 @@ function defineAccessControl(config) {
       const route = config.routes[key];
       if (!route)
         return false;
+      if (route.lifecycle?.status === "retired")
+        return false;
+      if (route.lifecycle?.status === "deprecated" && Date.parse(context?.now ?? new Date().toISOString()) >= Date.parse(route.lifecycle.expiresAt))
+        return false;
       if (route.feature && !features.includes(route.feature))
         return false;
       if (context?.stage && route.stages && !route.stages.includes(context.stage))
@@ -275,7 +307,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.14";
+var VERSION = "0.1.15";
 
 // src/security.ts
 var HEX = Array.from({ length: 256 }, (_, index) => index.toString(16).padStart(2, "0"));