@danypops/vehicle-core 0.17.1 → 0.18.1

package/dist/jobs/grant.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The Grant primitive's own wire-neutral shape: a resource budget bounding how much an
+ * already-authorized, already-running long-running operation may still do before it must ask
+ * for more. Mirrors VehicleJobWakeBudget's own convention (a plain, optional-per-dimension
+ * object, not a class) -- see wake-log.ts's own doc comment for that precedent. Every dimension
+ * is independently optional: a caller states only the ceilings that matter for its own operation
+ * (an operation with no real notion of "tokens" simply never sets maxTokens).
+ *
+ * Deliberately agent-flavored (turns/tool-calls/tokens) rather than a generic {maxCount, maxBytes}
+ * pair the way VehicleJobWakeBudget is -- Vehicle was built specifically for agent consumers
+ * (vehicle-client-pi exists precisely to project operations as Pi tools), so this vocabulary
+ * belongs here rather than being reinvented per-consumer.
+ */
+export interface VehicleGrantBudget {
+    readonly maxTurns?: number;
+    readonly maxToolCalls?: number;
+    readonly maxTokens?: number;
+    readonly maxWallClockMs?: number;
+}
+/**
+ * True the moment any one *set* dimension reaches zero or below -- the tightest dimension
+ * governs, not an average or a sum. A dimension the caller never set imposes no ceiling of its
+ * own. An entirely empty budget ({}) is never exhausted: that's an unbounded grant (every
+ * dimension omitted), not a zero one -- a caller that wants "no more of anything" states at
+ * least one dimension as 0, it doesn't rely on {} meaning that.
+ */
+export declare function grantBudgetExhausted(remaining: VehicleGrantBudget): boolean;
+/**
+ * Adds a top-up onto the current remaining budget, dimension by dimension. A dimension absent
+ * from the top-up is left exactly as it was; a dimension the current budget never had but the
+ * top-up introduces is taken as-is (not added to an implicit 0, since the current budget's own
+ * "never set" already means unbounded for that dimension -- introducing a ceiling for the first
+ * time via a top-up is a real, deliberate narrowing a caller must do explicitly, not an artifact
+ * of the merge itself).
+ */
+export declare function mergeGrantBudget(current: VehicleGrantBudget, additional: VehicleGrantBudget): VehicleGrantBudget;

package/dist/jobs/grant.js

@@ -0,0 +1,31 @@
+/**
+ * True the moment any one *set* dimension reaches zero or below -- the tightest dimension
+ * governs, not an average or a sum. A dimension the caller never set imposes no ceiling of its
+ * own. An entirely empty budget ({}) is never exhausted: that's an unbounded grant (every
+ * dimension omitted), not a zero one -- a caller that wants "no more of anything" states at
+ * least one dimension as 0, it doesn't rely on {} meaning that.
+ */
+export function grantBudgetExhausted(remaining) {
+    return ((remaining.maxTurns !== undefined && remaining.maxTurns <= 0) ||
+        (remaining.maxToolCalls !== undefined && remaining.maxToolCalls <= 0) ||
+        (remaining.maxTokens !== undefined && remaining.maxTokens <= 0) ||
+        (remaining.maxWallClockMs !== undefined && remaining.maxWallClockMs <= 0));
+}
+/**
+ * Adds a top-up onto the current remaining budget, dimension by dimension. A dimension absent
+ * from the top-up is left exactly as it was; a dimension the current budget never had but the
+ * top-up introduces is taken as-is (not added to an implicit 0, since the current budget's own
+ * "never set" already means unbounded for that dimension -- introducing a ceiling for the first
+ * time via a top-up is a real, deliberate narrowing a caller must do explicitly, not an artifact
+ * of the merge itself).
+ */
+export function mergeGrantBudget(current, additional) {
+    const merged = { ...current };
+    for (const key of ["maxTurns", "maxToolCalls", "maxTokens", "maxWallClockMs"]) {
+        const addition = additional[key];
+        if (addition === undefined)
+            continue;
+        merged[key] = (current[key] ?? 0) + addition;
+    }
+    return merged;
+}

package/dist/jobs/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./grant.js";
 export * from "./identity.js";
 export * from "./replay.js";
 export * from "./retention.js";

package/dist/jobs/index.js

@@ -1,3 +1,4 @@
+export * from "./grant.js";
 export * from "./identity.js";
 export * from "./replay.js";
 export * from "./retention.js";

package/dist/schemas/index.d.ts

@@ -2,3 +2,4 @@ export * from "./codec.js";
 export * from "./json.js";
 export * from "./loose-object.js";
 export * from "./presentation.js";
+export * from "./primitives.js";

package/dist/schemas/index.js

@@ -2,3 +2,4 @@ export * from "./codec.js";
 export * from "./json.js";
 export * from "./loose-object.js";
 export * from "./presentation.js";
+export * from "./primitives.js";

package/dist/schemas/primitives.d.ts

@@ -0,0 +1,37 @@
+import type { VehicleSchemaIssue } from "./codec.js";
+/** The `{ success: false, issues }` half of VehicleSchemaResult -- named on its own since every hand-written safeParse's failure branch is this exact shape, never a bare Error. */
+export interface VehicleSchemaFailure {
+    readonly success: false;
+    readonly issues: readonly VehicleSchemaIssue[];
+}
+/**
+ * A safeParse's own first, universal check: the value wasn't even an object. Every hand-written
+ * object-shaped VehicleSchemaCodec across the ecosystem re-derived this exact literal before this
+ * existed as a shared primitive -- one canonical wording now, not five near-identical copies.
+ */
+export declare function notAnObjectIssue(): VehicleSchemaFailure;
+/**
+ * One field-scoped failure. `path` accepts a single key (the common case: a top-level field) or
+ * a full path segment array (for a nested/array-indexed field, matching VehicleSchemaIssue.path's
+ * own `readonly (string | number)[]` shape directly) -- both real shapes existing hand-written
+ * safeParse implementations across the ecosystem already needed.
+ */
+export declare function schemaIssue(path: string | number | readonly (string | number)[], message: string): VehicleSchemaFailure;
+/** True for a real object value -- not null, not an array (JSON Schema's own object/array distinction; `typeof [] === "object"` is not what a caller checking "is this a plain object" means). */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** A non-empty string -- the shape every identifier-like field (workspaceId, ref, path, ...) across the ecosystem actually requires; an empty string is a real, distinct failure from "not a string at all". */
+export declare function isNonEmptyString(value: unknown): value is string;
+/** A real integer safely representable in a double -- the base every bounded-count/size field below builds on. */
+export declare function isSafeInteger(value: unknown): value is number;
+/** A safe integer that is zero or more -- e.g. an offset/cursor field where zero is a real, valid value, unlike a positive-only count. */
+export declare function isNonNegativeSafeInteger(value: unknown): value is number;
+/**
+ * A safe integer that is at least 1 -- the shape every bounded-count/size field (maxBytes,
+ * maxCount, maxResults, maxMatches, ...) across the ecosystem actually requires. `maximum`, when
+ * given, additionally caps the accepted value inclusively -- a field that must be positive AND
+ * never exceed some hard ceiling (e.g. a page size capped well below an unbounded read) is a real,
+ * recurring combination, not a hypothetical one.
+ */
+export declare function isPositiveSafeInteger(value: unknown, maximum?: number): value is number;
+/** An array whose every element is a string -- the shape every string-list field (labels, tags, pathspecs, ...) across the ecosystem actually requires; a mixed-type array is a real, distinct failure from "not an array at all". */
+export declare function isStringArray(value: unknown): value is string[];

package/dist/schemas/primitives.js

@@ -0,0 +1,47 @@
+/**
+ * A safeParse's own first, universal check: the value wasn't even an object. Every hand-written
+ * object-shaped VehicleSchemaCodec across the ecosystem re-derived this exact literal before this
+ * existed as a shared primitive -- one canonical wording now, not five near-identical copies.
+ */
+export function notAnObjectIssue() {
+    return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+}
+/**
+ * One field-scoped failure. `path` accepts a single key (the common case: a top-level field) or
+ * a full path segment array (for a nested/array-indexed field, matching VehicleSchemaIssue.path's
+ * own `readonly (string | number)[]` shape directly) -- both real shapes existing hand-written
+ * safeParse implementations across the ecosystem already needed.
+ */
+export function schemaIssue(path, message) {
+    return { success: false, issues: [{ path: Array.isArray(path) ? path : [path], message }] };
+}
+/** True for a real object value -- not null, not an array (JSON Schema's own object/array distinction; `typeof [] === "object"` is not what a caller checking "is this a plain object" means). */
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A non-empty string -- the shape every identifier-like field (workspaceId, ref, path, ...) across the ecosystem actually requires; an empty string is a real, distinct failure from "not a string at all". */
+export function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/** A real integer safely representable in a double -- the base every bounded-count/size field below builds on. */
+export function isSafeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value);
+}
+/** A safe integer that is zero or more -- e.g. an offset/cursor field where zero is a real, valid value, unlike a positive-only count. */
+export function isNonNegativeSafeInteger(value) {
+    return isSafeInteger(value) && value >= 0;
+}
+/**
+ * A safe integer that is at least 1 -- the shape every bounded-count/size field (maxBytes,
+ * maxCount, maxResults, maxMatches, ...) across the ecosystem actually requires. `maximum`, when
+ * given, additionally caps the accepted value inclusively -- a field that must be positive AND
+ * never exceed some hard ceiling (e.g. a page size capped well below an unbounded read) is a real,
+ * recurring combination, not a hypothetical one.
+ */
+export function isPositiveSafeInteger(value, maximum) {
+    return isSafeInteger(value) && value >= 1 && (maximum === undefined || value <= maximum);
+}
+/** An array whose every element is a string -- the shape every string-list field (labels, tags, pathspecs, ...) across the ecosystem actually requires; a mixed-type array is a real, distinct failure from "not an array at all". */
+export function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.17.1",
+	"version": "0.18.1",
 	"description": "Vehicle's runtime-neutral wire contract: operation descriptors, schema codecs, failure shapes. Zero runtime dependencies, zero Bun-specific code -- the one thing every Vehicle client and server package depends on.",
 	"license": "MIT",
 	"type": "module",

package/src/jobs/grant.ts

@@ -0,0 +1,53 @@
+/**
+ * The Grant primitive's own wire-neutral shape: a resource budget bounding how much an
+ * already-authorized, already-running long-running operation may still do before it must ask
+ * for more. Mirrors VehicleJobWakeBudget's own convention (a plain, optional-per-dimension
+ * object, not a class) -- see wake-log.ts's own doc comment for that precedent. Every dimension
+ * is independently optional: a caller states only the ceilings that matter for its own operation
+ * (an operation with no real notion of "tokens" simply never sets maxTokens).
+ *
+ * Deliberately agent-flavored (turns/tool-calls/tokens) rather than a generic {maxCount, maxBytes}
+ * pair the way VehicleJobWakeBudget is -- Vehicle was built specifically for agent consumers
+ * (vehicle-client-pi exists precisely to project operations as Pi tools), so this vocabulary
+ * belongs here rather than being reinvented per-consumer.
+ */
+export interface VehicleGrantBudget {
+	readonly maxTurns?: number;
+	readonly maxToolCalls?: number;
+	readonly maxTokens?: number;
+	readonly maxWallClockMs?: number;
+}
+
+/**
+ * True the moment any one *set* dimension reaches zero or below -- the tightest dimension
+ * governs, not an average or a sum. A dimension the caller never set imposes no ceiling of its
+ * own. An entirely empty budget ({}) is never exhausted: that's an unbounded grant (every
+ * dimension omitted), not a zero one -- a caller that wants "no more of anything" states at
+ * least one dimension as 0, it doesn't rely on {} meaning that.
+ */
+export function grantBudgetExhausted(remaining: VehicleGrantBudget): boolean {
+	return (
+		(remaining.maxTurns !== undefined && remaining.maxTurns <= 0) ||
+		(remaining.maxToolCalls !== undefined && remaining.maxToolCalls <= 0) ||
+		(remaining.maxTokens !== undefined && remaining.maxTokens <= 0) ||
+		(remaining.maxWallClockMs !== undefined && remaining.maxWallClockMs <= 0)
+	);
+}
+
+/**
+ * Adds a top-up onto the current remaining budget, dimension by dimension. A dimension absent
+ * from the top-up is left exactly as it was; a dimension the current budget never had but the
+ * top-up introduces is taken as-is (not added to an implicit 0, since the current budget's own
+ * "never set" already means unbounded for that dimension -- introducing a ceiling for the first
+ * time via a top-up is a real, deliberate narrowing a caller must do explicitly, not an artifact
+ * of the merge itself).
+ */
+export function mergeGrantBudget(current: VehicleGrantBudget, additional: VehicleGrantBudget): VehicleGrantBudget {
+	const merged: { -readonly [K in keyof VehicleGrantBudget]?: number } = { ...current };
+	for (const key of ["maxTurns", "maxToolCalls", "maxTokens", "maxWallClockMs"] as const) {
+		const addition = additional[key];
+		if (addition === undefined) continue;
+		merged[key] = (current[key] ?? 0) + addition;
+	}
+	return merged;
+}

package/src/jobs/index.ts

@@ -1,3 +1,4 @@
+export * from "./grant.js";
 export * from "./identity.js";
 export * from "./replay.js";
 export * from "./retention.js";

package/src/schemas/index.ts

@@ -2,3 +2,4 @@ export * from "./codec.js";
 export * from "./json.js";
 export * from "./loose-object.js";
 export * from "./presentation.js";
+export * from "./primitives.js";

package/src/schemas/primitives.ts

@@ -0,0 +1,62 @@
+import type { VehicleSchemaIssue } from "./codec.js";
+
+/** The `{ success: false, issues }` half of VehicleSchemaResult -- named on its own since every hand-written safeParse's failure branch is this exact shape, never a bare Error. */
+export interface VehicleSchemaFailure {
+	readonly success: false;
+	readonly issues: readonly VehicleSchemaIssue[];
+}
+
+/**
+ * A safeParse's own first, universal check: the value wasn't even an object. Every hand-written
+ * object-shaped VehicleSchemaCodec across the ecosystem re-derived this exact literal before this
+ * existed as a shared primitive -- one canonical wording now, not five near-identical copies.
+ */
+export function notAnObjectIssue(): VehicleSchemaFailure {
+	return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+}
+
+/**
+ * One field-scoped failure. `path` accepts a single key (the common case: a top-level field) or
+ * a full path segment array (for a nested/array-indexed field, matching VehicleSchemaIssue.path's
+ * own `readonly (string | number)[]` shape directly) -- both real shapes existing hand-written
+ * safeParse implementations across the ecosystem already needed.
+ */
+export function schemaIssue(path: string | number | readonly (string | number)[], message: string): VehicleSchemaFailure {
+	return { success: false, issues: [{ path: Array.isArray(path) ? path : [path], message }] };
+}
+
+/** True for a real object value -- not null, not an array (JSON Schema's own object/array distinction; `typeof [] === "object"` is not what a caller checking "is this a plain object" means). */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A non-empty string -- the shape every identifier-like field (workspaceId, ref, path, ...) across the ecosystem actually requires; an empty string is a real, distinct failure from "not a string at all". */
+export function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
+/** A real integer safely representable in a double -- the base every bounded-count/size field below builds on. */
+export function isSafeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value);
+}
+
+/** A safe integer that is zero or more -- e.g. an offset/cursor field where zero is a real, valid value, unlike a positive-only count. */
+export function isNonNegativeSafeInteger(value: unknown): value is number {
+	return isSafeInteger(value) && value >= 0;
+}
+
+/**
+ * A safe integer that is at least 1 -- the shape every bounded-count/size field (maxBytes,
+ * maxCount, maxResults, maxMatches, ...) across the ecosystem actually requires. `maximum`, when
+ * given, additionally caps the accepted value inclusively -- a field that must be positive AND
+ * never exceed some hard ceiling (e.g. a page size capped well below an unbounded read) is a real,
+ * recurring combination, not a hypothetical one.
+ */
+export function isPositiveSafeInteger(value: unknown, maximum?: number): value is number {
+	return isSafeInteger(value) && value >= 1 && (maximum === undefined || value <= maximum);
+}
+
+/** An array whose every element is a string -- the shape every string-list field (labels, tags, pathspecs, ...) across the ecosystem actually requires; a mixed-type array is a real, distinct failure from "not an array at all". */
+export function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}