@duckcodeailabs/dql-agent 1.6.21 → 1.6.23

package/dist/metadata/drafts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"drafts.d.ts","sourceRoot":"","sources":["../../src/metadata/drafts.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAUD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQjE;AAED,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,oBAAoB,GACxB,mBAAmB,CA0BrB"}
+{"version":3,"file":"drafts.d.ts","sourceRoot":"","sources":["../../src/metadata/drafts.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,8FAA8F;IAC9F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAUD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQjE;AAqGD,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,sBAAsB,GAAG,MAAM,CAW7E;AAED,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,oBAAoB,GACxB,mBAAmB,CAiCrB"}

package/dist/metadata/drafts.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { resolveLocalOwner } from './identity.js';
 const STOPWORDS = new Set([
     'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'do', 'for', 'from',
     'has', 'have', 'how', 'i', 'in', 'is', 'it', 'me', 'much', 'my', 'of',
@@ -16,16 +17,138 @@ export function deriveGeneratedDraftSlug(question) {
     const slug = tokens.join('_').slice(0, 60).replace(/_+$/, '');
     return slug || 'untitled_proposal';
 }
+/** Snake_case identifier rule the namer enforces: `^[a-z][a-z0-9_]*$`. */
+const SEMANTIC_NAME_RE = /^[a-z][a-z0-9_]*$/;
+/**
+ * Words that hint at the metric/entity being asked about. Kept tiny and
+ * convention-agnostic — this is a deterministic fallback, not an NLP model.
+ */
+const GRAIN_HINTS = [
+    { re: /\b(daily|per day|by day|each day)\b/i, grain: 'daily' },
+    { re: /\b(weekly|per week|by week|each week)\b/i, grain: 'weekly' },
+    { re: /\b(monthly|per month|by month|each month)\b/i, grain: 'monthly' },
+    { re: /\b(quarterly|per quarter|by quarter)\b/i, grain: 'quarterly' },
+    { re: /\b(yearly|annual|annually|per year|by year)\b/i, grain: 'yearly' },
+];
+/** Common analytic entities/measures we recognize for the rule-based fallback. */
+const ENTITY_HINTS = [
+    'orders', 'order', 'revenue', 'sales', 'customers', 'customer', 'users', 'user',
+    'sessions', 'session', 'payments', 'payment', 'subscriptions', 'subscription',
+    'churn', 'retention', 'signups', 'signup', 'spend', 'cost', 'profit', 'margin',
+    'shipments', 'shipment', 'products', 'product', 'accounts', 'account', 'leads',
+    'lead', 'tickets', 'ticket', 'visits', 'visit', 'transactions', 'transaction',
+];
+/** A "by <dimension>" phrase points at the key dimension of the question. */
+const DIMENSION_RE = /\bby\s+([a-z][a-z0-9 ]{1,30}?)(?:\s+(?:at|per|for|in|over|grouped|broken)\b|[?.,]|$)/i;
+function snakeTokens(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((token) => token.length > 0);
+}
+function toSnake(value) {
+    return snakeTokens(value).join('_').replace(/^_+|_+$/g, '');
+}
+/**
+ * Validate + normalize a provider-suggested block name. Returns a clean
+ * snake_case slug (deduped against `existing`) or undefined when the suggestion
+ * is unusable.
+ */
+function sanitizeProviderName(suggested, existing) {
+    if (typeof suggested !== 'string')
+        return undefined;
+    let candidate = suggested.trim().toLowerCase();
+    if (!candidate)
+        return undefined;
+    // Coerce light formatting (spaces / dashes / camelCase) into snake_case before
+    // validating, so a well-meaning but loosely-formatted suggestion still passes.
+    if (!SEMANTIC_NAME_RE.test(candidate)) {
+        candidate = candidate
+            .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '_')
+            .replace(/^_+|_+$/g, '');
+    }
+    if (!SEMANTIC_NAME_RE.test(candidate))
+        return undefined;
+    return dedupeSlug(candidate.slice(0, 60).replace(/_+$/, ''), existing);
+}
+/**
+ * Rule-based semantic extraction: entity (+ key dimension + grain) from the
+ * question, e.g. "total orders by geography at the daily level" →
+ * `orders_by_geography_daily`. Returns undefined when no entity is recognizable.
+ */
+function ruleBasedName(question) {
+    const lower = question.toLowerCase();
+    const tokens = snakeTokens(question);
+    // Entity: first recognized analytic noun, singular/plural insensitive.
+    const entity = ENTITY_HINTS.find((hint) => tokens.includes(hint));
+    if (!entity)
+        return undefined;
+    const parts = [entity];
+    // Key dimension: a "by <dimension>" phrase, reduced to its head noun.
+    const dimMatch = lower.match(DIMENSION_RE);
+    if (dimMatch) {
+        const dim = toSnake(dimMatch[1]);
+        if (dim && dim !== entity)
+            parts.push('by', dim);
+    }
+    // Grain: an explicit time grain hint.
+    const grainHint = GRAIN_HINTS.find((hint) => hint.re.test(lower));
+    if (grainHint)
+        parts.push(grainHint.grain);
+    const slug = parts.join('_').replace(/^_+|_+$/g, '');
+    return slug || undefined;
+}
+/** Append `_2`, `_3`, … until the slug is unused. */
+function dedupeSlug(slug, existing) {
+    if (!existing.has(slug))
+        return slug;
+    let n = 2;
+    while (existing.has(`${slug}_${n}`))
+        n += 1;
+    return `${slug}_${n}`;
+}
+/**
+ * Pick a SEMANTIC snake_case name for a builder-generated block.
+ *
+ * Priority:
+ *   1. A valid provider-suggested name (`^[a-z][a-z0-9_]*$`), deduped.
+ *   2. A rule-based extraction (entity + key dimension + grain), deduped.
+ *   3. The legacy question tokenizer (`deriveGeneratedDraftSlug`) — LAST resort.
+ *
+ * This deliberately avoids the old behavior of naming a block after the literal
+ * question (e.g. `can_you_build_the_total_orders_by_geography_at_the_level`).
+ */
+export function deriveSemanticDraftName(input) {
+    const existing = new Set(input.existingSlugs ?? []);
+    const fromProvider = sanitizeProviderName(input.providerName, existing);
+    if (fromProvider)
+        return fromProvider;
+    const fromRule = ruleBasedName(input.question);
+    if (fromRule)
+        return dedupeSlug(fromRule.slice(0, 60).replace(/_+$/, ''), existing);
+    // Last resort: the legacy tokenizer, still deduped so re-asks don't collide.
+    return dedupeSlug(deriveGeneratedDraftSlug(input.question), existing);
+}
 export function upsertGeneratedDraft(projectRoot, rec) {
     const { filePath, relativePath } = resolveGeneratedDraftPath(projectRoot, rec);
+    // Owner is the one field a human must confirm to certify — never let a captured
+    // draft be born owner-less (it would hard-block certification for no reason).
+    const owner = rec.owner?.trim() || resolveLocalOwner(projectRoot);
     if (existsSync(filePath)) {
         const existing = readFileSync(filePath, 'utf-8');
         const m = existing.match(/asked_times\s*=\s*(\d+)/);
         const prev = m ? Number.parseInt(m[1], 10) : 1;
         const next = Number.isFinite(prev) ? prev + 1 : 2;
-        const updated = m
+        let updated = m
             ? existing.replace(/asked_times\s*=\s*\d+/, `asked_times = ${next}`)
             : existing.replace(/\n\s*query\s*=/, `\n    asked_times = ${next}\n\n    query =`);
+        // Backfill owner on older owner-less drafts so re-asking makes them certifiable.
+        if (!/\n\s*owner\s*=/.test(updated)) {
+            updated = updated.replace(/(\n\s*status\s*=\s*"draft")/, `$1\n    owner = "${escapeDqlString(owner)}"`);
+        }
         writeFileSync(filePath, stampLastAsked(updated));
         return {
             path: relativePath,
@@ -34,7 +157,7 @@ export function upsertGeneratedDraft(projectRoot, rec) {
         };
     }
     mkdirSync(dirname(filePath), { recursive: true });
-    writeFileSync(filePath, renderGeneratedDraft(rec, relativePath));
+    writeFileSync(filePath, renderGeneratedDraft({ ...rec, owner }, relativePath));
     return {
         path: relativePath,
         askedTimes: 1,
@@ -66,6 +189,7 @@ function renderGeneratedDraft(rec, draftPath) {
     domain = "${escapeDqlString(rec.proposedDomain ?? 'misc')}"
     type = "custom"
     status = "draft"
+    owner = "${escapeDqlString(rec.owner ?? '')}"
     description = """${rec.question.replace(/"""/g, '\\"\\"\\"')}"""
 
     // Tier-2 generated proposal. This block is NOT certified.

package/dist/metadata/drafts.js.map

@@ -1 +1 @@
-{"version":3,"file":"drafts.js","sourceRoot":"","sources":["../../src/metadata/drafts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"drafts.js","sourceRoot":"","sources":["../../src/metadata/drafts.ts"],"names":[],"mappings":"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"}

package/dist/metadata/grain-gate.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Grain / contract gate for certified-block routing.
+ *
+ * Retrieval is keyword-based (FTS5/BM25), so the router can surface a certified
+ * block that is *close* to the question but answers a DIFFERENT grain than what
+ * was asked (e.g. an account-grain block for a region-grain question). Serving
+ * that as "Certified" is worse than refusing — it is a confidently wrong governed
+ * answer.
+ *
+ * Blocks already carry `grain`, `entities`, and `declaredOutputs`; this module
+ * uses them as a hard gate. Before a Tier-1 certified route is served, the
+ * question's requested grain/entity is compared with the candidate block's
+ * declared grain. Exact or compatible (coarser-rollup) grains pass; a genuine
+ * grain/entity mismatch demotes the answer to Tier-2 (generated, block-as-context).
+ *
+ * The gate is deliberately CONSERVATIVE: when the question has no clearly
+ * extractable grain, or the block declares no grain, it does NOT demote — it
+ * must not regress today's behavior or over-refuse true matches.
+ */
+import type { MetadataObject } from './catalog.js';
+import type { AnalysisQuestionPlan } from './analysis-planner.js';
+/** Coarsest-to-finest time grain ordering. Lower index = finer granularity. */
+declare const TIME_GRAIN_ORDER: readonly ["hour", "day", "week", "month", "quarter", "year"];
+type TimeGrain = (typeof TIME_GRAIN_ORDER)[number];
+export type GrainGateKind = 'no_requested_grain' | 'block_grain_unknown' | 'exact' | 'compatible_rollup' | 'mismatch';
+export interface RequestedGrain {
+    /** Canonical time grain requested, if the question implies one. */
+    time?: TimeGrain;
+    /**
+     * Entity/dimension grain tokens requested by the question (normalized,
+     * canonicalized to a synonym group representative where known).
+     */
+    entities: string[];
+    /** True when neither a time grain nor an entity grain could be extracted. */
+    empty: boolean;
+}
+export interface GrainGateResult {
+    /** Whether the candidate block may be served as a Tier-1 certified answer. */
+    allow: boolean;
+    kind: GrainGateKind;
+    /** Human-readable description of the requested grain (for routeReason). */
+    requestedGrainLabel: string;
+    /** Human-readable description of the block's declared grain (for routeReason). */
+    blockGrainLabel: string;
+    reason: string;
+}
+/**
+ * Extract the question's requested grain from the already-computed analysis
+ * plan. Conservative by design: we only treat a token as a requested grain when
+ * it is a recognized dimension/time word. Free-form named entities (e.g. a
+ * person's name used as a filter value) are NOT a grain request.
+ */
+export declare function requestedGrainFromPlan(plan: AnalysisQuestionPlan): RequestedGrain;
+/**
+ * Compare a certified block's declared grain / outputs / entities against the
+ * question's requested grain. Returns whether Tier-1 is still allowed and a
+ * structured reason.
+ */
+export declare function grainMatches(block: MetadataObject, requested: RequestedGrain): GrainGateResult;
+export {};
+//# sourceMappingURL=grain-gate.d.ts.map

package/dist/metadata/grain-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grain-gate.d.ts","sourceRoot":"","sources":["../../src/metadata/grain-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElE,+EAA+E;AAC/E,QAAA,MAAM,gBAAgB,8DAA+D,CAAC;AACtF,KAAK,SAAS,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAsCnD,MAAM,MAAM,aAAa,GACrB,oBAAoB,GACpB,qBAAqB,GACrB,OAAO,GACP,mBAAmB,GACnB,UAAU,CAAC;AAEf,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6EAA6E;IAC7E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,aAAa,CAAC;IACpB,2EAA2E;IAC3E,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kFAAkF;IAClF,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,cAAc,CAiBjF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,cAAc,GACxB,eAAe,CAqFjB"}

package/dist/metadata/grain-gate.js

@@ -0,0 +1,265 @@
+/**
+ * Grain / contract gate for certified-block routing.
+ *
+ * Retrieval is keyword-based (FTS5/BM25), so the router can surface a certified
+ * block that is *close* to the question but answers a DIFFERENT grain than what
+ * was asked (e.g. an account-grain block for a region-grain question). Serving
+ * that as "Certified" is worse than refusing — it is a confidently wrong governed
+ * answer.
+ *
+ * Blocks already carry `grain`, `entities`, and `declaredOutputs`; this module
+ * uses them as a hard gate. Before a Tier-1 certified route is served, the
+ * question's requested grain/entity is compared with the candidate block's
+ * declared grain. Exact or compatible (coarser-rollup) grains pass; a genuine
+ * grain/entity mismatch demotes the answer to Tier-2 (generated, block-as-context).
+ *
+ * The gate is deliberately CONSERVATIVE: when the question has no clearly
+ * extractable grain, or the block declares no grain, it does NOT demote — it
+ * must not regress today's behavior or over-refuse true matches.
+ */
+/** Coarsest-to-finest time grain ordering. Lower index = finer granularity. */
+const TIME_GRAIN_ORDER = ['hour', 'day', 'week', 'month', 'quarter', 'year'];
+/**
+ * Maps surface words (singular, after light normalization) to a canonical time
+ * grain. Both question terms and block grain tokens are run through this.
+ */
+const TIME_GRAIN_SYNONYMS = {
+    hour: 'hour', hourly: 'hour',
+    day: 'day', daily: 'day', date: 'day', dt: 'day',
+    week: 'week', weekly: 'week', wk: 'week',
+    month: 'month', monthly: 'month', mo: 'month', mtd: 'month',
+    quarter: 'quarter', quarterly: 'quarter', qtr: 'quarter', qtd: 'quarter',
+    year: 'year', yearly: 'year', annual: 'year', annually: 'year', yr: 'year', ytd: 'year',
+    season: 'year',
+};
+/**
+ * Known entity-grain synonym groups. Each group's members are treated as the
+ * same entity grain. This is intentionally small and high-confidence — unknown
+ * tokens fall back to literal comparison, never a forced match.
+ */
+const ENTITY_GRAIN_GROUPS = [
+    ['account', 'accounts'],
+    ['customer', 'customers', 'client', 'clients'],
+    ['user', 'users', 'member', 'members'],
+    ['region', 'regions', 'geo', 'market', 'territory'],
+    ['product', 'products', 'sku', 'item', 'items'],
+    ['order', 'orders'],
+    ['player', 'players', 'athlete', 'athletes'],
+    ['team', 'teams'],
+    ['vendor', 'vendors', 'supplier', 'suppliers', 'merchant', 'merchants'],
+    ['segment', 'segments', 'cohort', 'cohorts'],
+    ['channel', 'channels'],
+    ['department', 'departments', 'team'],
+    ['country', 'countries', 'nation'],
+    ['store', 'stores', 'location', 'locations'],
+];
+/**
+ * Extract the question's requested grain from the already-computed analysis
+ * plan. Conservative by design: we only treat a token as a requested grain when
+ * it is a recognized dimension/time word. Free-form named entities (e.g. a
+ * person's name used as a filter value) are NOT a grain request.
+ */
+export function requestedGrainFromPlan(plan) {
+    const time = extractTimeGrain([
+        ...plan.timeTerms,
+        ...plan.dimensionTerms,
+        plan.normalizedQuestion,
+    ]);
+    const entityTokens = new Set();
+    for (const term of [...plan.dimensionTerms, ...plan.metricTerms]) {
+        for (const token of grainTokens(term)) {
+            const canonical = canonicalEntityToken(token);
+            if (canonical)
+                entityTokens.add(canonical);
+        }
+    }
+    const entities = [...entityTokens];
+    return { time, entities, empty: !time && entities.length === 0 };
+}
+/**
+ * Compare a certified block's declared grain / outputs / entities against the
+ * question's requested grain. Returns whether Tier-1 is still allowed and a
+ * structured reason.
+ */
+export function grainMatches(block, requested) {
+    const requestedGrainLabel = describeRequestedGrain(requested);
+    // No-grain-no-demote: if the question carries no clearly-extractable grain,
+    // never demote — preserve current behavior.
+    if (requested.empty) {
+        return {
+            allow: true,
+            kind: 'no_requested_grain',
+            requestedGrainLabel,
+            blockGrainLabel: describeBlockGrain(block),
+            reason: 'question has no clearly-extractable grain; grain gate does not demote',
+        };
+    }
+    const blockGrain = blockGrainProfile(block);
+    const blockGrainLabel = describeBlockGrain(block);
+    // Backward compatible: a block with no declared grain/outputs/entities cannot
+    // be gated — we have nothing to compare against, so allow (don't over-refuse).
+    if (!blockGrain.time && blockGrain.entities.length === 0) {
+        return {
+            allow: true,
+            kind: 'block_grain_unknown',
+            requestedGrainLabel,
+            blockGrainLabel,
+            reason: 'block declares no grain/outputs/entities to gate against; allowing Tier 1',
+        };
+    }
+    // ---- Time grain check (only when the question requests a time grain) ----
+    if (requested.time) {
+        if (blockGrain.time) {
+            if (blockGrain.time === requested.time) {
+                // exact time match; fall through to entity check
+            }
+            else if (timeGrainIndex(blockGrain.time) < timeGrainIndex(requested.time)) {
+                // Block grain is FINER than requested (e.g. daily block, weekly
+                // question) → it can roll up. Compatible.
+                return {
+                    allow: true,
+                    kind: 'compatible_rollup',
+                    requestedGrainLabel,
+                    blockGrainLabel,
+                    reason: `block grain=${blockGrain.time} is finer than requested grain=${requested.time} → safe roll-up`,
+                };
+            }
+            else {
+                // Block grain is COARSER than requested (e.g. monthly block, daily
+                // question) → cannot answer the finer question. Mismatch.
+                return {
+                    allow: false,
+                    kind: 'mismatch',
+                    requestedGrainLabel,
+                    blockGrainLabel,
+                    reason: `certified block grain=${blockGrain.time} ≠ requested grain=${requested.time} → Tier 2`,
+                };
+            }
+        }
+        // Block declares no time grain but does declare an entity grain that the
+        // question does not request as a dimension → that is itself a likely
+        // entity mismatch, handled below.
+    }
+    // ---- Entity / dimension grain check ----
+    if (requested.entities.length > 0 && blockGrain.entities.length > 0) {
+        const overlap = requested.entities.some((entity) => blockGrain.entities.includes(entity));
+        if (!overlap) {
+            const reqEntity = requested.entities[0];
+            const blockEntity = blockGrain.entities[0];
+            return {
+                allow: false,
+                kind: 'mismatch',
+                requestedGrainLabel,
+                blockGrainLabel,
+                reason: `certified block grain=${blockEntity} ≠ requested grain=${reqEntity} → Tier 2`,
+            };
+        }
+    }
+    return {
+        allow: true,
+        kind: 'exact',
+        requestedGrainLabel,
+        blockGrainLabel,
+        reason: 'certified block grain satisfies the requested grain',
+    };
+}
+/**
+ * Build the block's declared grain profile from `grain`, `declaredOutputs`, and
+ * `entities` (read from the indexed payload).
+ */
+function blockGrainProfile(block) {
+    const payload = block.payload ?? {};
+    const grainStr = typeof payload.grain === 'string' ? payload.grain : '';
+    const declaredOutputs = stringArray(payload.declaredOutputs);
+    const entities = stringArray(payload.entities);
+    const time = extractTimeGrain([grainStr, ...declaredOutputs]);
+    const entityTokens = new Set();
+    // The declared `grain` string is the strongest signal (e.g. "account_id",
+    // "region", "customer_id"). Tokenize it and canonicalize known entity words.
+    for (const token of grainTokens(grainStr)) {
+        const canonical = canonicalEntityToken(token);
+        if (canonical)
+            entityTokens.add(canonical);
+    }
+    // Declared business entities are also an entity-grain signal.
+    for (const entity of entities) {
+        for (const token of grainTokens(entity)) {
+            const canonical = canonicalEntityToken(token);
+            if (canonical)
+                entityTokens.add(canonical);
+        }
+    }
+    // Output columns named like `<entity>_id` are a strong row-grain signal.
+    for (const output of declaredOutputs) {
+        for (const token of grainTokens(output)) {
+            const canonical = canonicalEntityToken(token);
+            if (canonical)
+                entityTokens.add(canonical);
+        }
+    }
+    return { time, entities: [...entityTokens] };
+}
+function extractTimeGrain(values) {
+    for (const value of values) {
+        for (const token of grainTokens(value)) {
+            const grain = TIME_GRAIN_SYNONYMS[token];
+            if (grain)
+                return grain;
+        }
+    }
+    return undefined;
+}
+/**
+ * Split a value into normalized grain tokens. Strips a trailing `_id`/`id`
+ * suffix so `account_id` and `account` compare equal, and lightly singularizes.
+ */
+function grainTokens(value) {
+    if (!value)
+        return [];
+    return value
+        .toLowerCase()
+        .replace(/[_\-./]+/g, ' ')
+        .replace(/[^a-z0-9 ]+/g, ' ')
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 2 && token !== 'id')
+        .map((token) => (token.endsWith('id') && token.length > 3 ? token.slice(0, -2) : token))
+        .map(singularize);
+}
+function singularize(token) {
+    if (token.endsWith('ies') && token.length > 4)
+        return `${token.slice(0, -3)}y`;
+    if (token.endsWith('ses') && token.length > 4)
+        return token.slice(0, -2);
+    if (token.endsWith('s') && token.length > 3)
+        return token.slice(0, -1);
+    return token;
+}
+/** Canonicalize a token to its entity-grain group representative, if known. */
+function canonicalEntityToken(token) {
+    const normalized = singularize(token);
+    for (const group of ENTITY_GRAIN_GROUPS) {
+        if (group.map(singularize).includes(normalized))
+            return singularize(group[0]);
+    }
+    return undefined;
+}
+function timeGrainIndex(grain) {
+    return TIME_GRAIN_ORDER.indexOf(grain);
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function describeRequestedGrain(requested) {
+    const parts = [requested.time, ...requested.entities].filter(Boolean);
+    return parts.length ? parts.join('+') : 'none';
+}
+function describeBlockGrain(block) {
+    const profile = blockGrainProfile(block);
+    const declared = typeof block.payload?.grain === 'string' ? block.payload.grain : '';
+    if (declared)
+        return declared;
+    const parts = [profile.time, ...profile.entities].filter(Boolean);
+    return parts.length ? parts.join('+') : 'unknown';
+}
+//# sourceMappingURL=grain-gate.js.map

package/dist/metadata/grain-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grain-gate.js","sourceRoot":"","sources":["../../src/metadata/grain-gate.ts"],"names":[],"mappings":"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"}

package/dist/metadata/identity.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Local OSS owner identity (spec 14, part C).
+ *
+ * A new DRAFT block must never be born with a "Missing owner" Certifier strike
+ * just because the OSS user never passed `--owner`. We resolve a sensible
+ * default owner ONCE and persist it, then stamp it across every draft-creating
+ * path (propose, generate, enrichment, /api/ai/build) when no explicit owner is
+ * supplied.
+ *
+ * Resolution order (first non-empty wins):
+ *   1. Persisted owner — `dql.config.json` `identity.owner`, else `.dql/local`.
+ *   2. git `user.email` (project-local, then global).
+ *   3. `$USER` / `$USERNAME` / OS user — `<user>@local`.
+ *   4. `guest@local` (guaranteed non-empty fallback).
+ *
+ * This module is deterministic and offline — it never calls a provider. The git
+ * lookup is best-effort and degrades silently when git is absent or the repo has
+ * no configured email.
+ */
+export interface ResolveOwnerOptions {
+    /**
+     * When provided, this owner wins over any persisted/derived value (the human
+     * passed `--owner` / `body.owner`). Empty / whitespace is treated as absent.
+     */
+    explicit?: string;
+    /**
+     * Persist the resolved owner so subsequent calls (and other tools) reuse it.
+     * Defaults to true. Set false for pure reads (e.g. a preview that must write
+     * nothing).
+     */
+    persist?: boolean;
+}
+/** Read a persisted owner from `dql.config.json` `identity.owner`, else `.dql/local/owner`. */
+export declare function readPersistedOwner(projectRoot: string): string | undefined;
+/**
+ * Persist the owner into `dql.config.json` `identity.owner` when the config
+ * exists; otherwise cache it under `.dql/local/owner`. Best-effort — a failure to
+ * persist never blocks the caller (the owner is still returned).
+ */
+export declare function persistOwner(projectRoot: string, owner: string): void;
+/**
+ * Resolve the default local OSS owner. Always returns a non-empty string. When
+ * an explicit owner is given it wins (and is persisted); otherwise the first
+ * persisted/derived value is used and persisted for reuse.
+ */
+export declare function resolveLocalOwner(projectRoot: string, options?: ResolveOwnerOptions): string;
+//# sourceMappingURL=identity.d.ts.map

package/dist/metadata/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/metadata/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAQD,+FAA+F;AAC/F,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAsB1E;AAiCD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA0BrE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAehG"}