agentfootprint/dist/types/recipes/identifier.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * identifier — the plain-name rule for a recipe id.
 *
 * Pattern: a total predicate + a refusal sentence. Pure, no dependencies.
 * Role:    recipes/ layer. Used by `defineAgentRecipe` and by the same
 *          validation `AgentBuilder.recipe()` runs on a hand-written literal.
 * Emits:   N/A.
 *
 * ## Two rules, and the second one is the interesting one
 *
 * 1. **A plain name.** Lower-case words joined by single hyphens:
 *    `support-desk`, `triage`, `refund-policy`. The id is what a person reads
 *    on a run manifest, in a conflict refusal and in a bug report, so it is
 *    spelled the way the rest of this library's public names are — for the
 *    common reader, not for the implementation.
 *
 * 2. **No version suffix.** `support-desk-2` and `support-desk-v2` are refused.
 *    A recipe already HAS a version field; an id that also encodes one produces
 *    two names for one composition, and then nothing groups: runs of `-2` and
 *    runs of the original look like two unrelated agents on the record, while
 *    the field that exists to tell them apart says `1.0.0` on both.
 *
 * ## The honest limit of rule 2
 *
 * It matches the version-suffix SHAPES — a final hyphen-separated segment that
 * is nothing but digits, optionally preceded by `v`. It does NOT catch an id
 * that merely ends in a digit, because `oauth2`, `s3-archive` and `sha256` are
 * real words and refusing them would be worse than missing `triage2`. Stated
 * rather than implied: this check narrows a mistake, it does not eliminate it.
 */
/** Whether `value` is a plain recipe id. Total: any input, no throw. */
export declare function isPlainRecipeId(value: unknown): value is string;
/**
 * The sentence a bad id gets. Names the value and the specific rule it broke —
 * the version-suffix case in particular, because the fix there is not
 * "spell it differently" but "use the field that already exists".
 *
 * @param callSite - the API the author called, e.g. `defineAgentRecipe`.
 */
export declare function recipeIdRefusal(callSite: string, value: unknown): string;
//# sourceMappingURL=identifier.d.ts.map