@quonfig/cli 0.2.3 → 0.4.0

package/dist/commands/cleanup/remove.js

@@ -1,10 +1,14 @@
 import { Flags } from '@oclif/core';
 import fs from 'node:fs';
 import path from 'node:path';
+import { SKILL_NAME } from '../../agent/skill-bundle.generated.js';
 import { APICommand } from '../../index.js';
 import { getAppUrl } from '../../util/domain-urls.js';
 import nameArg from '../../util/name-arg.js';
-const SKILL_NAME = 'qfg-flag-cleanup';
+// The public Quonfig agent skill (github.com/quonfig/skills, installed with
+// `qfg agent install-skill` or the Claude Code plugin). Its
+// references/retire-a-flag.md is the code-removal half of this workflow.
+const SKILL_REFERENCE = 'references/retire-a-flag.md';
 const GITIGNORE_ENTRY = '.qf/cleanup/';
 // SDK client method names worth grepping for in the customer's codebase.
 // Based on the surfaces the official Quonfig SDKs expose (sdk-node /
@@ -121,14 +125,16 @@ function ensureGitignoreEntry(cwd) {
 }
 export default class CleanupRemove extends APICommand {
     static args = { ...nameArg };
-    static description = `Write a cleanup payload for a ready-for-cleanup flag and hand off to the qfg-flag-cleanup Claude skill.
+    static description = `Write a cleanup payload for a ready-for-cleanup flag and hand off to the Quonfig agent skill.
 
 Modeled on \`qfg migrate my-code\` — this command never edits source files
 itself. It validates that the flag is marked readyForCleanup=true, refuses to
 proceed if there are still evals_2d > 0 (use --force to override), writes
 \`.qf/cleanup/<key>.json\` describing the flag's current rule shape +
-telemetry, and prints instructions to invoke the qfg-flag-cleanup skill which
-asks the engineer which value should "win" and applies the inlining.
+telemetry, and prints how to have your coding agent remove the call sites with
+the quonfig agent skill (its references/retire-a-flag.md), which asks the
+engineer which value should "win" and applies the inlining. Install the skill
+with \`qfg agent install-skill\` or \`claude plugin install quonfig@quonfig\`.
 
 The payload deliberately does NOT suggest a winning value; that's the
 engineer's call. Run \`qfg cleanup status <key>\` first if you want to inspect
@@ -208,9 +214,14 @@ telemetry before retiring.`;
         this.log(`Payload:      ${relPayloadPath}`);
         this.log(`Evals (2d):   ${totals.evals_2d}${payload.forced ? ' (--force overrode the safety gate)' : ''}`);
         this.log('');
-        this.log(`To remove this flag's call sites, invoke Claude with the ${SKILL_NAME} skill:`);
+        this.log(`To remove this flag's call sites, ask your coding agent to retire it with the quonfig agent skill`);
+        this.log(`(${SKILL_REFERENCE} covers this workflow), e.g. in Claude Code:`);
         this.log('');
-        this.log(`  claude "/${SKILL_NAME} ${key}"`);
+        this.log(`  claude "Retire the Quonfig flag ${key} using ${relPayloadPath}"`);
+        this.log('');
+        this.log(`No quonfig skill in this repo yet? Install it first:`);
+        this.log(`  qfg agent install-skill                    # writes .claude/skills/quonfig/`);
+        this.log(`  # or: claude plugin marketplace add quonfig/skills && claude plugin install quonfig@quonfig`);
         this.log('');
         this.log(`The skill will:`);
         this.log(`  1. Read ${relPayloadPath}`);

package/dist/commands/cleanup/status.js

@@ -42,13 +42,13 @@ export default class CleanupStatus extends APICommand {
     static description = `Drill into one ready-for-cleanup flag — show telemetry across all environments and the current rule shape.
 
 Use this after \`qfg cleanup list\` to inspect a specific flag before handing
-removal off to the qfg-flag-cleanup Claude skill. The eval counts come from
+removal off to the Quonfig agent skill. The eval counts come from
 analytics.configSparklines (the same backing data the per-flag sparklines on
 the flag detail page use), summed into 24h/2d/7d/30d windows so you can decide
 whether it's safe to retire.
 
 Pass --json for the structured object including the full rule shape per
-environment — the cleanup skill consumes this directly.`;
+environment — the agent skill consumes this directly.`;
     static examples = [
         '<%= config.bin %> <%= command.id %> my.flag.key',
         '<%= config.bin %> <%= command.id %> my.flag.key --json',

package/dist/commands/cleanup.js

@@ -4,14 +4,15 @@ export default class Cleanup extends BaseCommand {
 
 The cleanup workflow turns a flag's "Ready for cleanup" marker into an end-to-end
 removal flow: surface the flags that are safe to retire, hand the actual code
-removal to the qfg-flag-cleanup Claude skill, then delete the flag definition
-once the call sites are gone.
+removal to your coding agent with the Quonfig agent skill (install it with
+\`qfg agent install-skill\`), then delete the flag definition once the call
+sites are gone.
 
 Lifecycle (high-level):
   1. Owner flips readyForCleanup=true in the UI            (already exists)
   2. qfg cleanup list                                       see candidates + telemetry
   3. qfg cleanup status <key>                               drill into one flag
-  4. qfg cleanup remove <key>                               handoff to the cleanup skill
+  4. qfg cleanup remove <key>                               handoff to the agent skill
   5. PR merges, SDK redeploys, telemetry confirms 0 evals
   6. qfg cleanup verify <key>                               (optional) confirm safe
   7. qfg delete <key>                                       remove the flag definition`;

package/dist/commands/config-schema.js

@@ -89,6 +89,9 @@ CRITERION FIELDS
 Each criterion object has:
   operator        (required) — see operator table below
   propertyName    (required for PROP_* operators) — user property, e.g. "user.key", "user.plan"
+                  To target specific customers or users, match on the context KEY
+                  ("organization.key", "user.key"), not a slug, email or name.
+                  Find a key from a name with: qfg contexts search organization <name>
   valueToMatch    (required for all except ALWAYS_TRUE / IS_PRESENT / IS_NOT_PRESENT) — typed value to compare against
 
 ────────────────────────────────────────────────────────────
@@ -109,18 +112,18 @@ OPERATOR REFERENCE
   PROP_LESS_THAN_OR_EQUAL          int or double
   PROP_GREATER_THAN                int or double
   PROP_GREATER_THAN_OR_EQUAL       int or double
-  PROP_SEMVER_LESS_THAN            string               semver comparison; valueToMatch is a semver string like "4.0.9"
-  PROP_SEMVER_EQUAL                string               semver comparison; valueToMatch is a semver string like "4.0.9"
-  PROP_SEMVER_GREATER_THAN         string               semver comparison; valueToMatch is a semver string like "4.0.9"
-  PROP_BEFORE                      string (ISO 8601)    date/time comparison
-  PROP_AFTER                       string (ISO 8601)
+  PROP_SEMVER_LESS_THAN            string               semver comparison; SemVer 2.0 like "4.0.9" or "1.0.0-beta.1"; "4" / "4.1" read as 4.0.0 / 4.1.0; no "v"
+  PROP_SEMVER_EQUAL                string               semver comparison; same version grammar
+  PROP_SEMVER_GREATER_THAN         string               semver comparison; same version grammar
+  PROP_BEFORE                      int or string        epoch ms (int) or RFC3339 with Z/offset, e.g. "2025-01-01T00:00:00Z"; no date-only
+  PROP_AFTER                       int or string        same timestamp grammar
   PROP_MATCHES                     string               regex match
   PROP_DOES_NOT_MATCH              string
   IS_PRESENT                       (none)               propertyName is set on the evaluation context (no valueToMatch)
   IS_NOT_PRESENT                   (none)               propertyName is missing from the evaluation context (no valueToMatch)
   IN_SEG                           string               value = segment key (no propertyName needed)
   NOT_IN_SEG                       string               value = segment key (no propertyName needed)
-  IN_INT_RANGE                     int_range            value = {min, max}
+  IN_INT_RANGE                     int_range            value = {"start": 0, "end": 10}; [start, end); omit a bound for unbounded
   LOOKUP_KEY_IN                    string_list          matches if SDK lookup key is in the list
   LOOKUP_KEY_NOT_IN                string_list
 

package/dist/commands/contexts/search.d.ts

@@ -0,0 +1,15 @@
+import type { JsonObj } from '../../result.js';
+import { APICommand } from '../../index.js';
+export default class ContextsSearch extends APICommand {
+    static args: {
+        contextType: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+        query: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        environment: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        limit: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<number, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+    };
+    run(): Promise<JsonObj | void>;
+}

package/dist/commands/contexts/search.js

@@ -0,0 +1,78 @@
+import { Args, Flags } from '@oclif/core';
+import { APICommand } from '../../index.js';
+export default class ContextsSearch extends APICommand {
+    static args = {
+        contextType: Args.string({
+            description: 'Context type to search, e.g. organization or user (the part before ".key" in a rule)',
+            required: true,
+        }),
+        query: Args.string({
+            description: 'Case-insensitive text matched against each context key and its reported properties (e.g. a name)',
+            required: true,
+        }),
+    };
+    static description = `Find a context's key from a name, to target it in a rule.
+
+Targeting rules should match a context by its KEY (<contextType>.key, e.g.
+organization.key or user.key), not by a slug, email or name. This searches the
+contexts your SDKs have reported through telemetry, matching the query against
+each context's key and properties, and prints each match's key, its name and
+its email (blank when the context reported none), most recently seen first.
+
+Only contexts your SDKs have reported are searchable. If nothing matches, the key
+is unknown: get it from whoever owns that customer rather than targeting a slug
+or email instead.
+
+Pass a key as the query to see its name and email.
+
+--json prints {contexts: [{key, name, email?}]}: name is null when the context
+reported no name, and email is present only when it reported one.`;
+    static examples = [
+        '<%= config.bin %> <%= command.id %> organization formhealth',
+        '<%= config.bin %> <%= command.id %> user barry@example.com --environment production',
+        '<%= config.bin %> <%= command.id %> organization formhealth --json',
+    ];
+    static flags = {
+        environment: Flags.string({
+            description: 'Only contexts reported from this environment (default: every environment)',
+        }),
+        limit: Flags.integer({
+            default: 20,
+            description: 'Maximum number of matches (1-100)',
+            max: 100,
+            min: 1,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(ContextsSearch);
+        const request = await this.apiClient.post('/api/v1/contexts/searchKeys', {
+            contextType: args.contextType,
+            environment: flags.environment,
+            limit: flags.limit,
+            query: args.query,
+            workspaceId: this.workspaceId,
+        });
+        if (!request.ok) {
+            const serverError = request.error;
+            const errorMsg = serverError?.error || serverError?.json?.message || `Failed to search contexts: ${request.status}`;
+            return this.err(errorMsg, { serverError: request.error });
+        }
+        const contexts = (request.json?.contexts ?? []);
+        if (contexts.length === 0) {
+            this.log(`No context seen via telemetry matched "${args.query}" (type ${args.contextType}), so the key is unknown.\n` +
+                'Only contexts your SDKs have reported are searchable. Get the key from whoever owns that ' +
+                'customer; do not target a slug or email instead.');
+            return { contexts: [] };
+        }
+        const keyWidth = Math.max(...contexts.map((c) => c.key.length), 'KEY'.length);
+        const nameWidth = Math.max(...contexts.map((c) => (c.name ?? '').length), 'NAME'.length);
+        const row = (key, name, email) => `${key.padEnd(keyWidth)}  ${name.padEnd(nameWidth)}  ${email}`.trimEnd();
+        const lines = [row('KEY', 'NAME', 'EMAIL')];
+        for (const context of contexts) {
+            lines.push(row(context.key, context.name ?? '', context.email ?? ''));
+        }
+        lines.push('', `Target these in a rule with propertyName "${args.contextType}.key".`);
+        this.log(lines.join('\n'));
+        return { contexts };
+    }
+}

package/dist/commands/contexts.d.ts

@@ -0,0 +1,6 @@
+import { BaseCommand } from '../index.js';
+export default class Contexts extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/contexts.js

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../index.js';
+export default class Contexts extends BaseCommand {
+    static description = 'Look up contexts (organizations, users, ...) your SDKs have reported, to target them by key.';
+    static examples = ['<%= config.bin %> contexts search organization formhealth'];
+    async run() {
+        this.log('Use one of the contexts subcommands:');
+        this.log('  qfg contexts search CONTEXT_TYPE QUERY [--environment ENV] [--limit N] [--json]');
+        this.log('      # find a context key by name, e.g. qfg contexts search organization formhealth');
+    }
+}

package/dist/commands/set-default.js

@@ -32,7 +32,11 @@ To set a percentage rollout (gradual rollout / A/B test / canary deploy) instead
   qfg set-rollout my.flag --environment production --true-percent 20
 
 To see all current values and rules for a flag:
-  qfg info my.flag`;
+  qfg info my.flag
+
+To target specific organizations or users, write rules on their KEY
+(organization.key, user.key), not a slug or email; find a key from a name with:
+  qfg contexts search organization formhealth`;
     static examples = [
         '<%= config.bin %> <%= command.id %> my.flag.name                                          # prompts for value and env',
         '<%= config.bin %> <%= command.id %> my.flag.name --value=true --environment=staging',

package/dist/init/templates.js

@@ -5,6 +5,16 @@
  * user-editable.  Each starts with a comment so users know not to
  * hand-edit them.
  */
+import { SKILL_FILES } from '../agent/skill-bundle.generated.js';
+/**
+ * The qfg-vs-MCP steering and "setting a value keeps targeting" rules are
+ * shared with the Quonfig agent skill (github.com/quonfig/skills,
+ * references/writes.md). The skill is the single source; the cli vendors it
+ * at build time (scripts/sync-agent-skill.mjs) and AGENTS.md embeds it here.
+ */
+const SHARED_WRITES_SECTION = SKILL_FILES.find((f) => f.path === 'references/writes.md')
+    .content.trim()
+    .replaceAll(/^## /gm, '### ');
 const MANAGED_HEADER = '<!-- Managed by `qfg init` — do not edit manually. Run `qfg init` to update. -->';
 // ── README.md ──────────────────────────────────────────────────────────
 export function readmeTemplate() {
@@ -196,48 +206,19 @@ This is a Quonfig workspace repository. See \`CLAUDE.md\` for the complete schem
 5. Files must be in the correct directory for their \`type\`.
 6. See \`CLAUDE.md\` for the full list of value types, operators, and constraints.
 
-## \`qfg\` or the Quonfig MCP?
+## Hosted workspaces: \`qfg\`, the MCP, and how writes behave
 
 Only relevant if this workspace is *also* hosted on a Quonfig account. On the
 fully-local path, editing the JSON in this repo is the whole story.
 
-- **This repo is checked out and you have a shell** -> use \`qfg\`. The files are
-  already on disk, so reading them costs nothing.
-- **Slack, claude.ai, or anywhere without a checkout** -> use the Quonfig MCP
-  server. It reads and writes the hosted workspace directly. Do not try to shell
-  out to \`qfg\` from a surface that has no repo.
-
-Both surfaces cover the same everyday loop — create a flag or config, change what
-an environment serves, set a log level. (\`qfg\` has all of it today; the MCP's
-create/config/log-level verbs land with its v2 write surface.)
-
-## Setting a value KEEPS that environment's targeting rules
-
-Both surfaces write the same way, so learn it once:
-
-\`qfg set-default\` (alias \`toggle\`), \`qfg set-rollout\`, and the MCP
-\`set_flag\`/\`set_config\` verbs replace exactly ONE rule — the environment's
-**fallback**, the unconditional rule at the end of its rule list that decides
-what users receive when no targeting rule matches. Every targeting rule above
-it is kept, and both surfaces report how many. An environment with no rules of
-its own has them copied from default first, so inherited targeting is kept too.
-
-| Surface | By default | To set the value for EVERYONE |
-|---------|------------|-------------------------------|
-| \`qfg set-default\` / \`qfg set-rollout\` | Keeps targeting; reports "Kept N targeting rule(s)" | add \`--replace-targeting\` |
-| MCP \`set_flag\` / \`set_config\` | Keeps targeting; reports the kept count in its result | send \`replaceTargeting: true\` |
-
-Setting the value for everyone DELETES that environment's targeting rules. They
-stay in git history, and the write returns a \`previousCommitSha\` to restore from.
+${SHARED_WRITES_SECTION}
 
-**Still read before you write.** \`qfg info <key>\` (or MCP \`get_flag\`) shows the
-rules your value is about to sit next to. For anything a fallback cannot express —
-multi-rule targeting, reordering, editing one targeting rule — edit the JSON
-directly or use MCP \`set_document\`.
+## Application repos
 
-\`qfg log-level --target ...\` and MCP \`set_log_level\` are **surgical** in the same
-way: they upsert the level for the loggers you name and leave every other rule in
-place.
+This file covers the workspace (config) repo. In an application repo that
+*reads* these flags through a Quonfig SDK, install the Quonfig agent skill:
+\`qfg agent install-skill\` (or \`claude plugin install quonfig@quonfig\`).
+It covers SDK setup, creating and rolling out flags, and the MCP tools.
 `;
 }
 // ── Pre-commit hook ────────────────────────────────────────────────────

package/dist/util/encryption.js

@@ -33,7 +33,9 @@ export function decrypt(encryptedString, keyStringHex) {
     const encryptedBytes = forge.util.hexToBytes(encryptedDataPart);
     const ivBytes = forge.util.hexToBytes(ivPart);
     const tagBytes = forge.util.hexToBytes(authTagPart);
-    // Create decipher
+    // Create decipher. node-forge AES-GCM with the IV passed to start() below, not
+    // Node's deprecated IV-less crypto.createDecipher that this rule targets.
+    // nosemgrep: javascript.node-crypto.security.create-de-cipher-no-iv.create-de-cipher-no-iv
     const decipher = forge.cipher.createDecipher('AES-GCM', keyBytes);
     decipher.start({
         iv: ivBytes,

package/dist/verify/schema-error-reshape.d.ts

@@ -59,6 +59,11 @@ export declare function findOneOfTag(branches: unknown[], root: unknown): OneOfT
  * a single `oneOfTag` error at the union's position.
  */
 export declare function reshapeOneOfErrors<E extends SchemaErrorLike>(errors: readonly E[], rootSchema: unknown, value: unknown): (E | SchemaErrorLike)[];
+/**
+ * The two 0-based indexes a duplicate-items violation names, lower first,
+ * or undefined for any other message. Lets a caller mark both rows.
+ */
+export declare function duplicateItemIndexes(message: string): [number, number] | undefined;
 /** One error -> message. Undefined means "skip it, a nested error says why". */
 export declare function describeSchemaError(error: SchemaErrorLike): string | undefined;
 /**

package/dist/verify/schema-error-reshape.js

@@ -207,6 +207,25 @@ export function reshapeOneOfErrors(errors, rootSchema, value) {
     });
     return result;
 }
+/**
+ * `uniqueItems` wording. Ajv says `(items ## 3 and 1 are identical)`:
+ * 0-based, later item first, with a stray `##`. Lists are numbered from 1
+ * everywhere the user reads them, so name the pair by row number, lower
+ * first: `(items 2 and 4 are identical)`.
+ */
+function duplicateItemsMessage(first, second) {
+    const [a, b] = [first, second].sort((x, y) => x - y);
+    return `must NOT have duplicate items (items ${a + 1} and ${b + 1} are identical)`;
+}
+const DUPLICATE_ITEMS_MESSAGE = /^must NOT have duplicate items \(items (\d+) and (\d+) are identical\)$/;
+/**
+ * The two 0-based indexes a duplicate-items violation names, lower first,
+ * or undefined for any other message. Lets a caller mark both rows.
+ */
+export function duplicateItemIndexes(message) {
+    const match = DUPLICATE_ITEMS_MESSAGE.exec(message);
+    return match ? [Number(match[1]) - 1, Number(match[2]) - 1] : undefined;
+}
 function stringifyAllowed(entry) {
     return typeof entry === 'string' ? entry : JSON.stringify(entry);
 }
@@ -223,6 +242,10 @@ export function describeSchemaError(error) {
             return Array.isArray(params.allowedValues)
                 ? `${message}: ${params.allowedValues.map(stringifyAllowed).join(', ')}`
                 : message;
+        case 'uniqueItems':
+            return typeof params.i === 'number' && typeof params.j === 'number'
+                ? duplicateItemsMessage(params.i, params.j)
+                : message;
         case 'propertyNames':
             // The nested keyword error (which carries `propertyName`) says why.
             return undefined;

package/dist/verify/validate.js

@@ -28,7 +28,7 @@
 import { z } from 'zod';
 import { findMapKeyOrderWarnings, navigate, scanOrderedJson } from './map-key-order.js';
 import { compileSchema, validateAgainstSchema } from './schema-validator.js';
-import { DURATION_FORMAT_HINT, isValidIsoDuration, parseDoubleValue, parseIntValue } from './value-grammar.js';
+import { DURATION_FORMAT_HINT, INT_RANGE_FORMAT_HINT, isValidIntRange, isValidIsoDuration, isValidSemver, isValidTimestamp, parseDoubleValue, parseIntValue, SEMVER_FORMAT_HINT, TIMESTAMP_FORMAT_HINT, } from './value-grammar.js';
 // Inlined to keep this directory self-contained for the standalone bun-compile
 // build that runs as the qfg-verify pre-receive hook in app-gitea — that build
 // only copies cli/src/verify/, so any out-of-tree imports break it. Source of
@@ -139,10 +139,14 @@ const WeightedValuesSchema = z.object({
     }),
 });
 const RuleValueSchema = z.union([ValueSchema, WeightedValuesSchema]);
+// IN_INT_RANGE's valueToMatch (qfg-goi1.5.9). Criterion-only: a config value
+// can never be an int_range. Its shape is checked per operator below.
+const IntRangeValueSchema = z.object({ type: z.literal('int_range'), value: z.unknown() });
+const CriterionValueSchema = z.discriminatedUnion('type', [...ValueSchema.options, IntRangeValueSchema]);
 const CriterionSchema = z.object({
     propertyName: z.string().optional(),
     operator: OperatorSchema,
-    valueToMatch: ValueSchema.optional(),
+    valueToMatch: CriterionValueSchema.optional(),
 });
 const ConfigRuleSchema = z.object({
     criteria: z.array(CriterionSchema),
@@ -1295,6 +1299,50 @@ function validateRules(rules, file, context, expectedValueType, issues, variants
                     severity: 'error',
                 });
             }
+            const shapeIssue = criterionValueShapeIssue(criterion);
+            if (shapeIssue) {
+                issues.push({
+                    file,
+                    message: `${critCtx}: operator "${criterion.operator}" ${shapeIssue.problem}`,
+                    severity: 'error',
+                    suggestion: shapeIssue.hint,
+                });
+            }
+        }
+    }
+}
+/**
+ * The value shapes every SDK agrees to evaluate (qfg-goi1.5 R3-R5, Q5). A value
+ * outside them is not an error in any SDK at eval time: the rule just never
+ * matches, silently, and before qfg-goi1.5 some SDKs matched it anyway. Rejecting
+ * at write time is the only place a human sees the mistake.
+ */
+function criterionValueShapeIssue(criterion) {
+    const vtm = criterion.valueToMatch;
+    if (!vtm)
+        return undefined;
+    const shown = JSON.stringify(vtm.value);
+    switch (criterion.operator) {
+        case 'IN_INT_RANGE': {
+            if (vtm.type !== 'int_range' || !isValidIntRange(vtm.value))
+                return { hint: INT_RANGE_FORMAT_HINT, problem: `needs an int_range value; got ${vtm.type} ${shown}` };
+            return undefined;
+        }
+        case 'PROP_AFTER':
+        case 'PROP_BEFORE': {
+            if (!['double', 'int', 'string'].includes(vtm.type) || !isValidTimestamp(vtm.value))
+                return { hint: TIMESTAMP_FORMAT_HINT, problem: `needs a timestamp; got ${vtm.type} ${shown}` };
+            return undefined;
+        }
+        case 'PROP_SEMVER_EQUAL':
+        case 'PROP_SEMVER_GREATER_THAN':
+        case 'PROP_SEMVER_LESS_THAN': {
+            if (vtm.type !== 'string' || !isValidSemver(vtm.value))
+                return { hint: SEMVER_FORMAT_HINT, problem: `needs a version string; got ${vtm.type} ${shown}` };
+            return undefined;
+        }
+        default: {
+            return undefined;
         }
     }
 }

package/dist/verify/value-grammar.d.ts

@@ -11,3 +11,10 @@ export declare const DURATION_FORMAT_HINT = "Expected an ISO 8601 duration such
 export declare const isValidIsoDuration: (value: string) => boolean;
 export declare const parseIntValue: (value: string) => number | undefined;
 export declare const parseDoubleValue: (value: string) => number | undefined;
+export declare const TIMESTAMP_FORMAT_HINT = "Expected epoch milliseconds (a number or an all-digit string) or an RFC3339 timestamp with Z or an offset, such as 2025-01-01T00:00:00Z or 2025-01-01T09:00:00+09:00.";
+export declare const isValidRfc3339: (value: string) => boolean;
+export declare const isValidTimestamp: (value: unknown) => boolean;
+export declare const SEMVER_FORMAT_HINT = "Expected a SemVer 2.0 version such as 4.0.18, 1.0.0-beta.1 or 1.0.0+build.5, or an abbreviated 4 / 4.1 (read as 4.0.0 / 4.1.0). No \"v\" prefix.";
+export declare const isValidSemver: (value: unknown) => boolean;
+export declare const INT_RANGE_FORMAT_HINT = "Expected {\"start\": <int>, \"end\": <int>} with at least one bound; the range is [start, end) and a missing bound is unbounded.";
+export declare const isValidIntRange: (value: unknown) => boolean;

package/dist/verify/value-grammar.js

@@ -61,3 +61,55 @@ export const parseDoubleValue = (value) => {
     const double = Number(value);
     return Number.isFinite(double) ? double : undefined;
 };
+// The ONE timestamp grammar for PROP_BEFORE / PROP_AFTER (qfg-goi1.5 R5),
+// identical on the criterion and context sides in every SDK: a JSON number
+// (epoch ms), an all-digit string (epoch ms), or RFC3339 with an uppercase T
+// and a Z or numeric offset (fractional seconds allowed). Date-only,
+// offset-less and free-form strings are not timestamps.
+/* eslint-disable unicorn/better-regex */
+const RFC3339_PATTERN = /^(?<y>[0-9]{4})-(?<mo>[0-9]{2})-(?<d>[0-9]{2})T(?<h>[0-9]{2}):(?<mi>[0-9]{2}):(?<s>[0-9]{2})(?:\.[0-9]+)?(?:Z|[+-](?<oh>[0-9]{2}):(?<om>[0-9]{2}))$/;
+/* eslint-enable unicorn/better-regex */
+export const TIMESTAMP_FORMAT_HINT = 'Expected epoch milliseconds (a number or an all-digit string) or an RFC3339 timestamp with Z or an offset, such as 2025-01-01T00:00:00Z or 2025-01-01T09:00:00+09:00.';
+export const isValidRfc3339 = (value) => {
+    const g = RFC3339_PATTERN.exec(value)?.groups;
+    if (!g)
+        return false;
+    const [y, mo, d, h, mi, s] = [g.y, g.mo, g.d, g.h, g.mi, g.s].map(Number);
+    const daysInMonth = new Date(Date.UTC(y, mo, 0)).getUTCDate();
+    if (mo < 1 || mo > 12 || d < 1 || d > daysInMonth || h > 23 || mi > 59 || s > 59)
+        return false;
+    if (g.oh !== undefined && (Number(g.oh) > 23 || Number(g.om) > 59))
+        return false;
+    return true;
+};
+export const isValidTimestamp = (value) => {
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value !== 'string')
+        return false;
+    return parseIntValue(value) !== undefined || isValidRfc3339(value);
+};
+// The ONE version grammar for PROP_SEMVER_* (qfg-goi1.5 R4 + Q5): SemVer 2.0
+// (no leading zeros, optional prerelease and build on a full x.y.z), plus the
+// abbreviated forms "x" and "x.y", read as x.0.0 and x.y.0. A "v" prefix is
+// not a version.
+const NUM = '(?:0|[1-9][0-9]*)';
+const PRE_ID = '(?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)';
+const BUILD_ID = '[0-9a-zA-Z-]+';
+const SEMVER_PATTERN = new RegExp(`^${NUM}(?:\\.${NUM}(?:\\.${NUM}(?:-${PRE_ID}(?:\\.${PRE_ID})*)?(?:\\+${BUILD_ID}(?:\\.${BUILD_ID})*)?)?)?$`);
+export const SEMVER_FORMAT_HINT = 'Expected a SemVer 2.0 version such as 4.0.18, 1.0.0-beta.1 or 1.0.0+build.5, or an abbreviated 4 / 4.1 (read as 4.0.0 / 4.1.0). No "v" prefix.';
+export const isValidSemver = (value) => typeof value === 'string' && SEMVER_PATTERN.test(value);
+// IN_INT_RANGE (qfg-goi1.5 R3): an object with integer start and/or end (at
+// least one), each a safe integer or an all-digit string (the proto int64 JSON
+// form). Range is [start, end); a missing bound is unbounded.
+export const INT_RANGE_FORMAT_HINT = 'Expected {"start": <int>, "end": <int>} with at least one bound; the range is [start, end) and a missing bound is unbounded.';
+export const isValidIntRange = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    if (keys.length === 0 || keys.some((k) => k !== 'start' && k !== 'end'))
+        return false;
+    return Object.values(value).every((bound) => typeof bound === 'number'
+        ? Number.isSafeInteger(bound)
+        : typeof bound === 'string' && parseIntValue(bound) !== undefined);
+};

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "0.2.3";
+declare const _default: "0.4.0";
 export default _default;

package/dist/version.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED from package.json by scripts/generate-version.mjs — do not edit.
-export default '0.2.3';
+export default '0.4.0';