@malloydata/malloy 0.0.396 → 0.0.398

package/dist/annotation.d.ts

@@ -1,12 +1,96 @@
 import type { Tag } from '@malloydata/malloy-tag';
-import type { Annotation } from './model';
+import type { Annotation, DocumentLocation } from './model';
 import type { LogMessage } from './lang';
+/**
+ * @deprecated Argument shape for the deprecated RegExp form of
+ * {@link annotationToTag}. The RegExp form cannot see block annotations
+ * (`#|`…`|#`). Pass a route string to `annotationToTag` instead, or use the
+ * {@link Annotations} view on a tagged entity.
+ */
 export interface TagParseSpec {
     prefix?: RegExp;
 }
+/** One annotation, unparsed — its raw text and where its content begins. */
+export interface AnnotationText {
+    /** The annotation exactly as written — prefix + content. */
+    rawText: string;
+    /** Offset where the content begins; `rawText.slice(contentIndex)` is the content. */
+    contentIndex: number;
+    /** Where `rawText` begins in the source document. */
+    at: DocumentLocation;
+    /**
+     * For block annotations: characters of leading whitespace removed from
+     * each body line by the translator's dedent pass. A BYO parser that wants
+     * source-mapped error columns adds this to the parser's reported column for
+     * body lines (`source_col = indentStripped + parser_col`).
+     */
+    indentStripped?: number;
+}
+/** An {@link AnnotationText} that also carries its route (`''` is MOTLY). */
+export interface RoutedAnnotation extends AnnotationText {
+    route: string;
+}
+/**
+ * Collect annotations, using the shared prefix parser.
+ * - no `route`: every annotation, each carrying its own `route` (the only way
+ *   to reach one whose prefix is malformed).
+ * - a `route`: only annotations on that route, `route` omitted from each result
+ *   (you passed it); malformed prefixes excluded.
+ */
+export declare function collectAnnotations(annote: Annotation | undefined): RoutedAnnotation[];
+export declare function collectAnnotations(annote: Annotation | undefined, route: string): AnnotationText[];
+/**
+ * @deprecated The RegExp form cannot see block annotations (`#|`…`|#`). Use
+ * `new Annotations(annote).texts(route)` instead, or the {@link Annotations}
+ * view on a tagged entity (`entity.annotations.texts(route)`).
+ */
 export declare function annotationToTaglines(annote: Annotation | undefined, prefix?: RegExp): string[];
 export interface MalloyTagParse {
     tag: Tag;
     log: LogMessage[];
 }
+/** Parse the annotations on `route` (default `''`, the MOTLY tag route) as MOTLY. */
+export declare function annotationToTag(annote: Annotation | undefined, route?: string): MalloyTagParse;
+/**
+ * @deprecated The RegExp `prefix` form cannot see block annotations
+ * (`#|`…`|#`) and cannot report content offsets for error mapping. Pass a route
+ * string (the other overload), or use {@link Annotations.parseAsTag} on a
+ * tagged entity.
+ */
 export declare function annotationToTag(annote: Annotation | undefined, spec?: TagParseSpec): MalloyTagParse;
+/**
+ * The route-aware annotation API for a tagged entity.
+ *
+ * An annotation has a *prefix* (everything from `#`/`##` up to the first
+ * whitespace) that resolves to a *route* — a namespace key. Built-in routes:
+ * `''` (MOTLY tags, the human default), `!` (compiler flags), `@` (persistence
+ * directives), `"` (doc-string markdown). Apps stake their own routes with
+ * brackets: `#(myApp) ...` is route `myApp`. The grammar (forms, bracket
+ * pairs, malformation warnings) lives in `./prefix.ts`.
+ *
+ * All annotation reading lives here, written once; each tagged class only has
+ * to say *where* its annotation is (by handing it to the constructor). Unlike
+ * the deprecated RegExp readers (`tagParse`/`getTaglines`), this sees block
+ * annotations.
+ */
+export declare class Annotations {
+    private readonly annote;
+    constructor(annote: Annotation | undefined);
+    /**
+     * Raw annotation text strings (prefix + content) — all routes if `route` is
+     * omitted, just that route's otherwise. The route-based successor to the
+     * deprecated `getTaglines`. For source-mapped offsets (bring-your-own
+     * parsers), see {@link forRoute}.
+     */
+    texts(route?: string): string[];
+    /**
+     * Your route's annotations as objects (`rawText` + `contentIndex` + `at`) —
+     * the bring-your-own-parser door. A non-MOTLY app (e.g. JSON on its own
+     * route) reads these to slice the content (`rawText.slice(contentIndex)`)
+     * itself and map its parser's errors back to source via `at`. Malformed-prefix
+     * annotations are excluded.
+     */
+    forRoute(route: string): AnnotationText[];
+    /** Parse a route's annotations as a MOTLY tag. Default `''` is the tag route. */
+    parseAsTag(route?: string): MalloyTagParse;
+}

package/dist/annotation.js

@@ -1,50 +1,80 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Annotations = void 0;
+exports.collectAnnotations = collectAnnotations;
 exports.annotationToTaglines = annotationToTaglines;
 exports.annotationToTag = annotationToTag;
 const malloy_tag_1 = require("@malloydata/malloy-tag");
+const prefix_1 = require("./prefix");
+/** Every Note of an annotation, inherited first, in document order. */
+function* notesInOrder(annote) {
+    if (annote.inherits)
+        yield* notesInOrder(annote.inherits);
+    if (annote.blockNotes)
+        yield* annote.blockNotes;
+    if (annote.notes)
+        yield* annote.notes;
+}
+function collectAnnotations(annote, route) {
+    if (route === undefined) {
+        return Array.from(notesInOrder(annote !== null && annote !== void 0 ? annote : {}), note => {
+            const { route: noteRoute, contentIndex } = (0, prefix_1.parsePrefix)(note.text);
+            return {
+                rawText: note.text,
+                contentIndex,
+                at: note.at,
+                route: noteRoute,
+                indentStripped: note.indentStripped,
+            };
+        });
+    }
+    const matching = [];
+    for (const note of notesInOrder(annote !== null && annote !== void 0 ? annote : {})) {
+        const parsed = (0, prefix_1.parsePrefix)(note.text);
+        if (parsed.route === route && parsed.malformation !== 'malformed-route') {
+            matching.push({
+                rawText: note.text,
+                contentIndex: parsed.contentIndex,
+                at: note.at,
+                indentStripped: note.indentStripped,
+            });
+        }
+    }
+    return matching;
+}
 /**
  * Collect all matching Notes from an Annotation, walking the inherits
  * chain. Returns notes in inheritance order (inherited first).
+ *
+ * @deprecated RegExp prefix matching; use {@link collectAnnotations} with a route.
  */
 function collectNotes(annote, prefix) {
-    const inherited = annote.inherits
-        ? collectNotes(annote.inherits, prefix)
-        : [];
-    const allNotes = [];
-    if (annote.blockNotes) {
-        allNotes.push(...annote.blockNotes);
-    }
-    if (annote.notes) {
-        allNotes.push(...annote.notes);
-    }
-    if (prefix) {
-        const matching = allNotes.filter(note => note.text.match(prefix));
-        return inherited.concat(matching);
-    }
-    return inherited.concat(allNotes);
+    const notes = [...notesInOrder(annote)];
+    return prefix ? notes.filter(note => note.text.match(prefix)) : notes;
 }
+/**
+ * @deprecated The RegExp form cannot see block annotations (`#|`…`|#`). Use
+ * `new Annotations(annote).texts(route)` instead, or the {@link Annotations}
+ * view on a tagged entity (`entity.annotations.texts(route)`).
+ */
 function annotationToTaglines(annote, prefix) {
     return collectNotes(annote || {}, prefix).map(n => n.text);
 }
-function annotationToTag(annote, spec = {}) {
-    const prefix = spec.prefix || /^##? /;
-    annote || (annote = {});
-    const notes = collectNotes(annote, prefix);
+/** Parse a run of Notes as MOTLY into one Tag, collecting errors. */
+function parseTaglines(lines) {
     const allErrs = [];
     const session = new malloy_tag_1.TagParser();
-    for (const note of notes) {
+    for (const line of lines) {
         const origin = {
-            url: note.at.url,
-            startLine: note.at.range.start.line,
-            startColumn: note.at.range.start.character,
+            url: line.at.url,
+            startLine: line.at.range.start.line,
+            startColumn: line.at.range.start.character,
         };
-        const noteParse = session.parseAnnotation(note.text, origin);
-        allErrs.push(...noteParse.log.map((e) => mapMalloyError(e, note)));
+        const noteParse = session.parseAnnotation(line.text, origin);
+        allErrs.push(...noteParse.log.map((e) => mapMalloyError(e, line)));
     }
     const tag = session.finish();
-    const refErrors = tag.validateReferences();
-    for (const refError of refErrors) {
+    for (const refError of tag.validateReferences()) {
         allErrs.push({
             code: 'tag-reference-error',
             severity: 'warn',
@@ -53,25 +83,78 @@ function annotationToTag(annote, spec = {}) {
     }
     return { tag, log: allErrs };
 }
-function mapMalloyError(e, note) {
-    // Calculate prefix length (same logic as stripPrefix in malloy-tag)
-    let prefixLen = 0;
-    if (note.text[0] === '#') {
-        const skipTo = note.text.search(/[ \n]/);
-        if (skipTo > 0) {
-            prefixLen = skipTo;
-        }
+function annotationToTag(annote, arg) {
+    if (typeof arg === 'object') {
+        const prefix = arg.prefix || /^##? /;
+        return parseTaglines(collectNotes(annote !== null && annote !== void 0 ? annote : {}, prefix));
+    }
+    const matched = collectAnnotations(annote, arg !== null && arg !== void 0 ? arg : '');
+    return parseTaglines(matched.map(a => ({
+        text: a.rawText,
+        at: a.at,
+        indentStripped: a.indentStripped,
+    })));
+}
+/**
+ * The route-aware annotation API for a tagged entity.
+ *
+ * An annotation has a *prefix* (everything from `#`/`##` up to the first
+ * whitespace) that resolves to a *route* — a namespace key. Built-in routes:
+ * `''` (MOTLY tags, the human default), `!` (compiler flags), `@` (persistence
+ * directives), `"` (doc-string markdown). Apps stake their own routes with
+ * brackets: `#(myApp) ...` is route `myApp`. The grammar (forms, bracket
+ * pairs, malformation warnings) lives in `./prefix.ts`.
+ *
+ * All annotation reading lives here, written once; each tagged class only has
+ * to say *where* its annotation is (by handing it to the constructor). Unlike
+ * the deprecated RegExp readers (`tagParse`/`getTaglines`), this sees block
+ * annotations.
+ */
+class Annotations {
+    constructor(annote) {
+        this.annote = annote;
     }
-    // Map error position to source location
-    // e.line is 0-based line within the (stripped) input
-    // e.offset is 0-based column within that line
-    // TODO: For block annotations, lines > 0 have indentation stripped by
-    // stripBlockIndent, so e.offset doesn't account for the removed columns.
-    // This makes error squigglies misaligned on block annotation body lines.
+    /**
+     * Raw annotation text strings (prefix + content) — all routes if `route` is
+     * omitted, just that route's otherwise. The route-based successor to the
+     * deprecated `getTaglines`. For source-mapped offsets (bring-your-own
+     * parsers), see {@link forRoute}.
+     */
+    texts(route) {
+        const items = route === undefined
+            ? collectAnnotations(this.annote)
+            : collectAnnotations(this.annote, route);
+        return items.map(a => a.rawText);
+    }
+    /**
+     * Your route's annotations as objects (`rawText` + `contentIndex` + `at`) —
+     * the bring-your-own-parser door. A non-MOTLY app (e.g. JSON on its own
+     * route) reads these to slice the content (`rawText.slice(contentIndex)`)
+     * itself and map its parser's errors back to source via `at`. Malformed-prefix
+     * annotations are excluded.
+     */
+    forRoute(route) {
+        return collectAnnotations(this.annote, route);
+    }
+    /** Parse a route's annotations as a MOTLY tag. Default `''` is the tag route. */
+    parseAsTag(route = '') {
+        return annotationToTag(this.annote, route);
+    }
+}
+exports.Annotations = Annotations;
+function mapMalloyError(e, note) {
+    var _a;
+    // MOTLY reports `e.line` / `e.offset` into the *stripped* note text it
+    // parsed. To map back to source:
+    //   line 0 (opener line):    col = opener_col + prefix_len + e.offset
+    //   line N>0 (body lines):   col = indentStripped + e.offset
+    // `indentStripped` is the per-line dedent recorded on the Note by the
+    // translator (uniform per block, so the same formula serves every body
+    // line). Prefix length is everything before the separator, via parsePrefix.
     const line = note.at.range.start.line + e.line;
     const character = e.line === 0
-        ? note.at.range.start.character + prefixLen + e.offset
-        : e.offset;
+        ? note.at.range.start.character + prefixLength(note.text) + e.offset
+        : ((_a = note.indentStripped) !== null && _a !== void 0 ? _a : 0) + e.offset;
     const loc = { line, character };
     return {
         code: 'tag-parse-error',
@@ -79,11 +162,14 @@ function mapMalloyError(e, note) {
         message: e.message,
         at: {
             url: note.at.url,
-            range: {
-                start: loc,
-                end: loc,
-            },
+            range: { start: loc, end: loc },
         },
     };
 }
+/** Length of the annotation prefix per malloy-tag's `stripPrefix`: index of
+ *  the first whitespace, or 0 if none. */
+function prefixLength(text) {
+    const { contentIndex } = (0, prefix_1.parsePrefix)(text);
+    return contentIndex === text.length ? 0 : contentIndex - 1;
+}
 //# sourceMappingURL=annotation.js.map

package/dist/api/core.js

@@ -56,7 +56,6 @@ const lang_1 = require("../lang");
 const model_1 = require("../model");
 const to_stable_1 = require("../to_stable");
 const sql_block_1 = require("../model/sql_block");
-const annotation_1 = require("../annotation");
 const malloy_tag_1 = require("@malloydata/malloy-tag");
 const util_1 = require("./util");
 const timing_1 = require("../timing");
@@ -506,9 +505,7 @@ function statedCompileQuery(state) {
                 defaultRowLimit: state.defaultRowLimit,
             });
             timer.contribute([sqlTimer.stop()]);
-            const modelAnnotations = (0, annotation_1.annotationToTaglines)(result.modelDef.annotation).map(l => ({
-                value: l,
-            }));
+            const modelAnnotations = (0, to_stable_1.toStableAnnotations)(result.modelDef.annotation);
             let source;
             if (query.compositeResolvedSourceDef) {
                 source = query.compositeResolvedSourceDef;
@@ -522,9 +519,7 @@ function statedCompileQuery(state) {
                     source = (0, model_1.safeRecordGet)(result.modelDef.contents, query.structRef);
                 }
             }
-            const sourceAnnotations = (0, annotation_1.annotationToTaglines)(source.annotation).map(l => ({
-                value: l,
-            }));
+            const sourceAnnotations = (0, to_stable_1.toStableAnnotations)(source.annotation);
             const sourceMetadataTag = malloy_tag_1.Tag.withPrefix('#(malloy) ');
             sourceMetadataTag.set(['source', 'name'], translatedQuery.sourceExplore);
             const sourceArguments = (_b = translatedQuery.sourceArguments) !== null && _b !== void 0 ? _b : ((0, model_1.isSourceDef)(source) ? source.arguments : undefined);

package/dist/api/foundation/core.d.ts

@@ -5,6 +5,7 @@ import type { Dialect } from '../../dialect';
 import type { BuildGraph, CompileQueryOptions } from './types';
 import { Tag } from '@malloydata/malloy-tag';
 import type { MalloyTagParse, TagParseSpec } from '../../annotation';
+import { Annotations } from '../../annotation';
 import type * as Malloy from '@malloydata/malloy-interfaces';
 import type { Taggable } from '../../taggable';
 declare abstract class Entity {
@@ -101,6 +102,7 @@ export declare class Explore extends Entity implements Taggable {
     isExploreField(): this is ExploreField;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
     private parsedModelTag?;
     get modelTag(): Tag;
     /**
@@ -141,6 +143,7 @@ export declare class AtomicField extends Entity implements Taggable {
     get type(): AtomicFieldType;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
     isIntrinsic(): boolean;
     isQueryField(): this is QueryField;
     isExploreField(): this is ExploreField;
@@ -208,6 +211,7 @@ export declare class QueryField extends Query implements Taggable {
     constructor(turtleDef: TurtleDef, parent: Explore, source?: Query);
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
     isQueryField(): this is QueryField;
     isExploreField(): this is ExploreField;
     isAtomicField(): this is AtomicField;
@@ -223,6 +227,7 @@ export declare class ExploreField extends Explore {
     get isRecord(): boolean;
     get isArray(): boolean;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
+    get annotations(): Annotations;
     isQueryField(): this is QueryField;
     isExploreField(): this is ExploreField;
     isAtomicField(): this is AtomicField;
@@ -282,6 +287,7 @@ export declare class Model implements Taggable {
     get givens(): ReadonlyMap<string, Given>;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
     /**
      * Retrieve a document reference for the token at the given position within
      * the document that produced this model.
@@ -419,6 +425,7 @@ export declare class PersistSource implements Taggable {
      * Get annotation taglines matching an optional prefix.
      */
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
     /**
      * The connection name for this source.
      */
@@ -484,6 +491,7 @@ export declare class Given implements Taggable {
     get location(): DocumentLocation | undefined;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
 }
 export declare class PreparedQuery implements Taggable {
     private _model;
@@ -494,6 +502,7 @@ export declare class PreparedQuery implements Taggable {
     get _modelDef(): ModelDef;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
     /**
      * Generate the SQL for this query.
      *
@@ -537,6 +546,7 @@ export declare class PreparedResult implements Taggable {
     static fromJson({ query, modelDef, }: PreparedResultJSON): PreparedResult;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
     get annotation(): Annotation | undefined;
     get modelAnnotation(): Annotation | undefined;
     get modelTag(): Tag;

package/dist/api/foundation/core.js

@@ -154,8 +154,11 @@ class Explore extends Entity {
     getTaglines(prefix) {
         return (0, annotation_1.annotationToTaglines)(this._structDef.annotation, prefix);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this._structDef.annotation);
+    }
     get modelTag() {
-        this.parsedModelTag || (this.parsedModelTag = (0, annotation_1.annotationToTag)(this._structDef.modelAnnotation).tag);
+        this.parsedModelTag || (this.parsedModelTag = new annotation_1.Annotations(this._structDef.modelAnnotation).parseAsTag().tag);
         return this.parsedModelTag;
     }
     /**
@@ -465,6 +468,9 @@ class AtomicField extends Entity {
     getTaglines(prefix) {
         return (0, annotation_1.annotationToTaglines)(this.fieldTypeDef.annotation, prefix);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this.fieldTypeDef.annotation);
+    }
     isIntrinsic() {
         return (0, model_1.fieldIsIntrinsic)(this.fieldTypeDef);
     }
@@ -666,6 +672,9 @@ class QueryField extends Query {
     getTaglines(prefix) {
         return (0, annotation_1.annotationToTaglines)(this.turtleDef.annotation, prefix);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this.turtleDef.annotation);
+    }
     isQueryField() {
         return true;
     }
@@ -719,6 +728,9 @@ class ExploreField extends Explore {
     tagParse(spec) {
         return (0, annotation_1.annotationToTag)(this._structDef.annotation, spec);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this._structDef.annotation);
+    }
     isQueryField() {
         return false;
     }
@@ -807,6 +819,9 @@ class Model {
     getTaglines(prefix) {
         return (0, annotation_1.annotationToTaglines)(this.modelDef.annotation, prefix);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this.modelDef.annotation);
+    }
     /**
      * Retrieve a document reference for the token at the given position within
      * the document that produced this model.
@@ -932,7 +947,7 @@ class Model {
      */
     getBuildPlan() {
         // Require experimental.persistence compiler flag
-        const modelTag = this.tagParse({ prefix: /^##! / }).tag;
+        const modelTag = this.annotations.parseAsTag('!').tag;
         if (!modelTag.has('experimental', 'persistence')) {
             throw new Error('Model must have ##! experimental.persistence to use getBuildPlan()');
         }
@@ -1057,6 +1072,9 @@ class PersistSource {
     getTaglines(prefix) {
         return this.explore.getTaglines(prefix);
     }
+    get annotations() {
+        return this.explore.annotations;
+    }
     /**
      * The connection name for this source.
      */
@@ -1159,6 +1177,9 @@ class Given {
     getTaglines(prefix) {
         return (0, annotation_1.annotationToTaglines)(this._internal.annotation, prefix);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this._internal.annotation);
+    }
 }
 exports.Given = Given;
 class PreparedQuery {
@@ -1177,6 +1198,9 @@ class PreparedQuery {
     getTaglines(prefix) {
         return (0, annotation_1.annotationToTaglines)(this._query.annotation, prefix);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this._query.annotation);
+    }
     /**
      * Generate the SQL for this query.
      *
@@ -1281,6 +1305,9 @@ class PreparedResult {
     getTaglines(prefix) {
         return (0, annotation_1.annotationToTaglines)(this.inner.annotation, prefix);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this.inner.annotation);
+    }
     get annotation() {
         return this.inner.annotation;
     }
@@ -1288,7 +1315,7 @@ class PreparedResult {
         return this.modelDef.annotation;
     }
     get modelTag() {
-        return (0, annotation_1.annotationToTag)(this.modelDef.annotation).tag;
+        return new annotation_1.Annotations(this.modelDef.annotation).parseAsTag().tag;
     }
     /**
      * @return The name of the connection this query should be run against.
@@ -1361,9 +1388,7 @@ class PreparedResult {
         const structs = this.inner.structs;
         const struct = structs[structs.length - 1];
         const schema = { fields: (0, to_stable_1.convertFieldInfos)(struct, struct.fields) };
-        const annotations = (0, annotation_1.annotationToTaglines)(this.inner.annotation).map(l => ({
-            value: l,
-        }));
+        const annotations = (0, to_stable_1.toStableAnnotations)(this.inner.annotation);
         const metadataAnnot = struct.resultMetadata
             ? (0, to_stable_1.getResultStructMetadataAnnotation)(struct, struct.resultMetadata)
             : undefined;
@@ -1392,9 +1417,7 @@ class PreparedResult {
                 .set(['query_name'], this.inner.queryName || struct.name)
                 .toString(),
         });
-        const modelAnnotations = (0, annotation_1.annotationToTaglines)(this.modelDef.annotation).map(l => ({
-            value: l,
-        }));
+        const modelAnnotations = (0, to_stable_1.toStableAnnotations)(this.modelDef.annotation);
         return {
             schema,
             data,

package/dist/api/foundation/runtime.js

@@ -1010,7 +1010,7 @@ class QueryMaterializer extends FluentState {
                 buildManifest = undefined;
             }
             if (buildManifest) {
-                const modelTag = preparedQuery.model.tagParse({ prefix: /^##! / }).tag;
+                const modelTag = preparedQuery.model.annotations.parseAsTag('!').tag;
                 if (!modelTag.has('experimental', 'persistence')) {
                     if (explicitManifest) {
                         // Explicitly passed non-empty manifest requires persistence support

package/dist/lang/composite-source-utils.js

@@ -547,7 +547,7 @@ function getPartitionCompositeFilter(partitionComposite, fieldUsage) {
 function getPartitionCompositeDesc(annotation, structDef, logTo) {
     if (annotation === undefined)
         return undefined;
-    const compilerFlags = (0, annotation_1.annotationToTag)(annotation, { prefix: /^#!\s*/ }).tag;
+    const compilerFlags = new annotation_1.Annotations(annotation).parseAsTag('!').tag;
     const partitionCompositeTag = compilerFlags.tag('experimental', 'partition_composite');
     if (partitionCompositeTag === undefined)
         return undefined;

package/dist/lang/malloy-to-ast.d.ts

@@ -92,6 +92,13 @@ export declare class MalloyToAST extends AbstractParseTreeVisitor<ast.MalloyElem
      */
     protected parseTime(pcx: ParserRuleContext, parse: (s: string) => ast.ExpressionDef | undefined): ast.ExpressionDef;
     protected getAnnotation(cx: parse.AnnotationContext): Note;
+    /**
+     * Warn if the annotation prefix is not a well-formed route. The note is still
+     * stored either way — the malformation only drives the diagnostic, never the
+     * IR. Warnings fire at note construction; inherited annotations carry no
+     * malformation marker through the IR and are not re-warned by importers.
+     */
+    private warnIfMalformedPrefix;
     protected getNotes(cx: HasAnnotations): Note[];
     protected getIsNotes(cx: parse.IsDefineContext): Note[];
     visitMalloyDocument(pcx: parse.MalloyDocumentContext): ast.Document;

package/dist/lang/malloy-to-ast.js

@@ -62,6 +62,7 @@ const AbstractParseTreeVisitor_1 = require("antlr4ts/tree/AbstractParseTreeVisit
 const ast = __importStar(require("./ast"));
 const parse_log_1 = require("./parse-log");
 const Interval_1 = require("antlr4ts/misc/Interval");
+const prefix_1 = require("../prefix");
 const ast_1 = require("./ast");
 const parse_utils_1 = require("./parse-utils");
 const malloy_types_1 = require("../model/malloy_types");
@@ -271,12 +272,26 @@ class MalloyToAST extends AbstractParseTreeVisitor_1.AbstractParseTreeVisitor {
         return this.astAt(def, pcx);
     }
     getAnnotation(cx) {
-        const text = (0, parse_utils_1.getAnnotationText)(cx, (wcx, msg) => {
-            this.contextError(wcx, 'block-annotation-warning', msg, {
-                severity: 'warn',
-            });
-        });
-        return { text: text, at: this.getLocation(cx) };
+        const note = (0, parse_utils_1.noteFromAnnotation)(cx, this.parseInfo);
+        this.warnIfMalformedPrefix(note.text, cx);
+        return note;
+    }
+    /**
+     * Warn if the annotation prefix is not a well-formed route. The note is still
+     * stored either way — the malformation only drives the diagnostic, never the
+     * IR. Warnings fire at note construction; inherited annotations carry no
+     * malformation marker through the IR and are not re-warned by importers.
+     */
+    warnIfMalformedPrefix(text, cx) {
+        const parsed = (0, prefix_1.parsePrefix)(text);
+        if (parsed.malformation === undefined)
+            return;
+        // The slice up to contentIndex is "prefix + separator"; trim trailing
+        // whitespace to land on the prefix the user wrote. (A no-content single-
+        // line note like `#malformed\n` exposes this: contentIndex === text.length
+        // but the slice still ends at the `\n`.)
+        const prefix = text.slice(0, parsed.contentIndex).replace(/\s+$/, '');
+        this.contextError(cx, parsed.malformation, { prefix });
     }
     getNotes(cx) {
         return cx.annotation().map(a => this.getAnnotation(a));
@@ -1533,10 +1548,11 @@ class MalloyToAST extends AbstractParseTreeVisitor_1.AbstractParseTreeVisitor {
                 this.contextError(pcx, 'unclosed-block-annotation', 'Block annotation is not closed, add correctly indented "|##"');
             }
         }
-        const allNotes = pcx.docAnnotation().map(a => ({
-            text: (0, parse_utils_1.getAnnotationText)(a),
-            at: this.getLocation(pcx),
-        }));
+        const allNotes = pcx.docAnnotation().map(a => {
+            const note = (0, parse_utils_1.noteFromAnnotation)(a, this.parseInfo);
+            this.warnIfMalformedPrefix(note.text, a);
+            return note;
+        });
         const tags = new ast.ModelAnnotation(allNotes);
         this.updateCompilerFlags(tags);
         return tags;

package/dist/lang/malloy-to-stable-query.js

@@ -101,9 +101,9 @@ class MalloyToQuery extends AbstractParseTreeVisitor_1.AbstractParseTreeVisitor
      * @returns Array of texts for the annotations
      */
     getAnnotations(cx) {
-        const annotations = cx.annotation().map(a => {
-            return { value: (0, parse_utils_1.getAnnotationText)(a) };
-        });
+        const annotations = cx.annotation().map(a => ({
+            value: (0, parse_utils_1.getAnnotationText)(a),
+        }));
         return annotations.length > 0 ? annotations : undefined;
     }
     getIsAnnotations(cx) {

package/dist/lang/parse-log.d.ts

@@ -358,7 +358,12 @@ type MessageParameterTypes = {
     'failed-to-parse-function-name': string;
     'orphaned-object-annotation': string;
     'unclosed-block-annotation': string;
-    'block-annotation-warning': string;
+    'malformed-route': {
+        prefix: string;
+    };
+    'reserved-route': {
+        prefix: string;
+    };
     'misplaced-model-annotation': string;
     'unexpected-non-source-query-expression-node': string;
     'sql-not-like': string;

package/dist/lang/parse-log.js

@@ -105,6 +105,14 @@ exports.MESSAGE_FORMATTERS = {
         message: e,
         tag: 'restricted-mode',
     }),
+    'malformed-route': e => ({
+        message: `Annotation prefix \`${e.prefix}\` is not a well-formed route — write \`# ...\` for a tag (note the space) or \`#(name)\` for an app route`,
+        severity: 'warn',
+    }),
+    'reserved-route': e => ({
+        message: `Annotation prefix \`${e.prefix}\` uses an unclaimed sigil; punct-only prefixes are reserved for Malloy's own use`,
+        severity: 'warn',
+    }),
 };
 function makeLogMessage(code, parameters, options) {
     var _a, _b, _c, _d, _e;

package/dist/lang/parse-malloy.js

@@ -478,7 +478,7 @@ class TranslateStep {
         // seeding (e.g. TestTranslator's compilerFlags option) survive.
         if (extendingModel && !this.importedAnnotations) {
             const parseCompilerFlagsTimer = new timing_1.Timer('parse_compiler_flags');
-            that.compilerFlagSrc.push(...(0, annotation_1.annotationToTaglines)(extendingModel.annotation, /^##! /));
+            that.compilerFlagSrc.push(...new annotation_1.Annotations(extendingModel.annotation).texts('!'));
             stepTimer.contribute([parseCompilerFlagsTimer.stop()]);
             this.importedAnnotations = true;
         }

package/dist/lang/parse-tree-walkers/model-annotation-walker.js

@@ -32,18 +32,10 @@ class ModelAnnotationWalker {
         this.parseInfo = parseInfo;
         this.notes = [];
     }
-    getLocation(cx) {
-        return {
-            url: this.parseInfo.sourceURL,
-            range: this.translator.rangeFromContext(cx),
-        };
-    }
     enterDocAnnotations(pcx) {
-        const allNotes = pcx.docAnnotation().map(a => ({
-            text: (0, parse_utils_1.getAnnotationText)(a),
-            at: this.getLocation(pcx),
-        }));
-        this.notes.push(...allNotes);
+        for (const a of pcx.docAnnotation()) {
+            this.notes.push((0, parse_utils_1.noteFromAnnotation)(a, this.parseInfo));
+        }
     }
     get annotation() {
         return { notes: this.notes };

package/dist/lang/parse-utils.d.ts

@@ -1,6 +1,8 @@
 import type { ParserRuleContext } from 'antlr4ts';
 import type { DocAnnotationContext } from './lib/Malloy/MalloyParser';
 import { type StringContext, type ShortStringContext, type SqlStringContext, type IdContext, AnnotationContext } from './lib/Malloy/MalloyParser';
+import type { Note } from '../model/malloy_types';
+import type { MalloyParseInfo } from './malloy-parse-info';
 /**
  * Take the text of a matched string, including the matching quote
  * characters, and return the actual contents of the string after
@@ -35,6 +37,12 @@ export declare function unIndent(parts: (string | unknown)[]): void;
  * @returns string part and an error list.
  */
 export declare function getPlainString(cx: HasString, strictCheck?: boolean): [string | undefined, ParserRuleContext[]];
-type AnnotationWarn = (cx: ParserRuleContext, msg: string) => void;
-export declare function getAnnotationText(cx: AnnotationContext | DocAnnotationContext, warn?: AnnotationWarn): string;
+/**
+ * Build the IR `Note` for an annotation: reads the text, dedents the body if
+ * it's a block, and computes the source `at` from the parse context. The
+ * single entry point for going from a parse-tree annotation to an IR note.
+ */
+export declare function noteFromAnnotation(cx: AnnotationContext | DocAnnotationContext, parseInfo: MalloyParseInfo): Note;
+/** Text-only reader, for callers that don't need an IR `Note`. */
+export declare function getAnnotationText(cx: AnnotationContext | DocAnnotationContext): string;
 export {};

package/dist/lang/parse-utils.js

@@ -30,9 +30,11 @@ exports.idToStr = idToStr;
 exports.getOptionalId = getOptionalId;
 exports.unIndent = unIndent;
 exports.getPlainString = getPlainString;
+exports.noteFromAnnotation = noteFromAnnotation;
 exports.getAnnotationText = getAnnotationText;
 const MalloyParser_1 = require("./lib/Malloy/MalloyParser");
 const malloy_tag_1 = require("@malloydata/malloy-tag");
+const utils_1 = require("./utils");
 /**
  * Take the text of a matched string, including the matching quote
  * characters, and return the actual contents of the string after
@@ -182,51 +184,109 @@ function getPlainString(cx, strictCheck = false) {
     // string: shortString | sqlString; So this will never happen
     return ['', errorList];
 }
-function stripBlockIndent(lines, column, cx, warn) {
-    if (column === 0) {
-        return lines.join('');
-    }
-    const prefix = ' '.repeat(column);
-    let warnedLeft = false;
-    let warnedTab = false;
-    return lines
-        .map(line => {
-        if (warn && !warnedTab && line.slice(0, column).includes('\t')) {
-            warn(cx, 'Block annotation indentation contains tabs, use spaces');
-            warnedTab = true;
-        }
-        if (line.startsWith(prefix)) {
-            return line.slice(column);
+/**
+ * Python `textwrap.dedent`-style: find the longest leading-whitespace prefix
+ * common to every non-blank body line and strip it from each line that starts
+ * with it. Blank (whitespace-only) lines don't constrain the prefix. Returns
+ * the stripped text and the number of characters removed per line — the
+ * latter is stored on the `Note` so payload-parser error columns can be
+ * mapped back to source (`source_col = indentStripped + parser_col`).
+ *
+ * Replaces an older "strip exactly opener_column spaces" rule that fired
+ * warnings for less-indented lines and had no clean column mapping when
+ * stripping was inconsistent. Common prefix is uniform per block, so column
+ * mapping is one number per block.
+ */
+function dedentBlockLines(lines) {
+    let common;
+    for (const line of lines) {
+        const content = line.replace(/\r?\n$/, '');
+        if (!/\S/.test(content))
+            continue;
+        const indent = content.match(/^[ \t]*/)[0];
+        if (common === undefined) {
+            common = indent;
+            continue;
         }
-        if (warn && !warnedLeft && !warnedTab && line.match(/\S/)) {
-            warn(cx, 'Block annotation content is left of the opening #|');
-            warnedLeft = true;
+        let n = 0;
+        while (n < common.length && n < indent.length && common[n] === indent[n]) {
+            n++;
         }
-        return line;
-    })
-        .join('');
+        common = common.slice(0, n);
+        if (common === '')
+            break;
+    }
+    const prefix = common !== null && common !== void 0 ? common : '';
+    if (prefix === '')
+        return { text: lines.join(''), indentStripped: 0 };
+    return {
+        text: lines
+            .map(line => (line.startsWith(prefix) ? line.slice(prefix.length) : line))
+            .join(''),
+        indentStripped: prefix.length,
+    };
 }
 function stripTrailingNewline(s) {
-    return s.endsWith('\n') ? s.slice(0, -1) : s;
+    // A trailing line ending may be CRLF or LF — strip either.
+    return s.replace(/\r?\n$/, '');
 }
-function getAnnotationText(cx, warn) {
+/**
+ * Annotation note text is normalized to LF line endings, so a block's stored
+ * text and content are identical regardless of the source's CRLF/LF style.
+ * The lexer keeps the source `\r` in token text (it sits at line ends, after a
+ * line's content); this is where it is dropped.
+ */
+function normalizeEol(s) {
+    return s.replace(/\r\n/g, '\n');
+}
+/**
+ * Read the text and dedent amount of an annotation from its parse tree.
+ * Internal — public callers want `noteFromAnnotation` or `getAnnotationText`.
+ */
+function readAnnotation(cx) {
     if (cx instanceof MalloyParser_1.AnnotationContext) {
         const annot = cx.ANNOTATION();
         if (annot)
-            return annot.text;
+            return { text: normalizeEol(annot.text), indentStripped: 0 };
         const block = cx.blockAnnotation();
         const beginToken = block.BLOCK_ANNOTATION_BEGIN();
         const textLines = block.BLOCK_ANNOTATION_TEXT().map(t => t.text);
-        return stripTrailingNewline(beginToken.text +
-            stripBlockIndent(textLines, beginToken.symbol.charPositionInLine, cx, warn));
+        const dedented = dedentBlockLines(textLines);
+        return {
+            text: normalizeEol(stripTrailingNewline(beginToken.text + dedented.text)),
+            indentStripped: dedented.indentStripped,
+        };
     }
     const doc = cx.DOC_ANNOTATION();
     if (doc)
-        return doc.text;
+        return { text: normalizeEol(doc.text), indentStripped: 0 };
     const block = cx.docBlockAnnotation();
     const beginToken = block.DOC_BLOCK_ANNOTATION_BEGIN();
     const textLines = block.BLOCK_ANNOTATION_TEXT().map(t => t.text);
-    return stripTrailingNewline(beginToken.text +
-        stripBlockIndent(textLines, beginToken.symbol.charPositionInLine, cx, warn));
+    const dedented = dedentBlockLines(textLines);
+    return {
+        text: normalizeEol(stripTrailingNewline(beginToken.text + dedented.text)),
+        indentStripped: dedented.indentStripped,
+    };
+}
+/**
+ * Build the IR `Note` for an annotation: reads the text, dedents the body if
+ * it's a block, and computes the source `at` from the parse context. The
+ * single entry point for going from a parse-tree annotation to an IR note.
+ */
+function noteFromAnnotation(cx, parseInfo) {
+    const { text, indentStripped } = readAnnotation(cx);
+    const at = {
+        url: parseInfo.sourceURL,
+        range: (0, utils_1.rangeFromContext)(parseInfo.sourceInfo, cx),
+    };
+    const note = { text, at };
+    if (indentStripped > 0)
+        note.indentStripped = indentStripped;
+    return note;
+}
+/** Text-only reader, for callers that don't need an IR `Note`. */
+function getAnnotationText(cx) {
+    return readAnnotation(cx).text;
 }
 //# sourceMappingURL=parse-utils.js.map

package/dist/model/malloy_types.d.ts

@@ -1138,6 +1138,13 @@ export interface Annotation {
 export interface Note {
     text: string;
     at: DocumentLocation;
+    /**
+     * For block annotations: characters of leading whitespace removed from each
+     * body line by the dedent pass. Used to map payload-parser error columns
+     * back to source (`source_col = indentStripped + parser_col` for body lines).
+     * Omitted for single-line notes and blocks with no common indent.
+     */
+    indentStripped?: number;
 }
 /** Annotations with a uuid to make it easier to stream */
 export interface ModelAnnotation extends Annotation {

package/dist/model/persist_utils.js

@@ -24,7 +24,7 @@ function resolveSource(modelDef, name) {
 function checkPersistAnnotation(source) {
     if (!source.annotation)
         return { persist: false, log: [] };
-    const { tag, log } = (0, annotation_1.annotationToTag)(source.annotation, { prefix: /^#@ / });
+    const { tag, log } = new annotation_1.Annotations(source.annotation).parseAsTag('@');
     return { persist: tag.has('persist'), log };
 }
 /**

package/dist/model/query_node.js

@@ -206,7 +206,7 @@ class QueryStruct {
     modelCompilerFlags() {
         if (this._modelTag === undefined) {
             const annotation = this.structDef.modelAnnotation;
-            const { tag } = (0, annotation_1.annotationToTag)(annotation, { prefix: /^##!\s*/ });
+            const { tag } = new annotation_1.Annotations(annotation).parseAsTag('!');
             this._modelTag = tag;
         }
         return this._modelTag;

package/dist/prefix.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The result of parsing an annotation's leading prefix.
+ *
+ * An annotation is `prefix sep content`. `parsePrefix` splits the captured
+ * annotation text at the first whitespace, strips the sigil (`#`/`##` plus an
+ * optional block `|`), and classifies the routing into one of three forms.
+ * `route` is one field; `contentIndex` and `malformation` are equally why this
+ * routine exists.
+ */
+export interface ParsedPrefix {
+    /** The route the prefix resolves to. `''` is the MOTLY (empty) route. */
+    route: string;
+    /**
+     * Offset into the annotation text where the content begins;
+     * `text.slice(contentIndex)` is the content, with the single separator
+     * character excluded.
+     */
+    contentIndex: number;
+    /**
+     * Set iff the prefix is not a well-formed route. The annotation is still
+     * stored and reachable via the all-routes API; this only drives a warning.
+     * - `malformed-route`: not one of the three forms — a bare word, an unclosed
+     *   or mismatched bracket, an empty bracketed name, or trailing junk.
+     * - `reserved-route`: a punct-only (sigil) routing that Malloy has not
+     *   claimed; the punct-only namespace is reserved for Malloy's own use.
+     */
+    malformation?: 'malformed-route' | 'reserved-route';
+}
+/**
+ * Parse the leading prefix of a captured annotation.
+ *
+ * `text` is the entire annotation as the lexer captured it, marker included: a
+ * single line `#... content`, or a block `#|...\n<body>` whose body the lexer
+ * has already de-indented and whose closer it has removed. This routine never
+ * parses the content — it returns where the content begins.
+ *
+ * The prefix runs from the marker to the **first whitespace**; that boundary
+ * never moves (no bracket or quote changes it, so a route can never contain
+ * whitespace). After stripping the sigil (`^##?\|?`), the routing matches one
+ * of three forms:
+ *
+ *   1. empty                 -> route `''`        (MOTLY, the human default)
+ *   2. PUNCT+ (no bracket)   -> sigil route       (reserved; unclaimed warns)
+ *   3. OPEN ... CLOSE        -> route = bracketed text (opaque app route)
+ *
+ * Anything else is `malformed-route`. Bracket pairs are `()`, `<>`, `[]`, `{}`;
+ * the route is everything up to the matching close (first close wins, no
+ * nesting), taken literally — no character classification, so `#(bar-chart)`,
+ * `#(https://x/y)`, and `#(v1.2.3)` are all just their bracketed text.
+ */
+export declare function parsePrefix(text: string): ParsedPrefix;

package/dist/prefix.js

@@ -0,0 +1,99 @@
+"use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePrefix = parsePrefix;
+/**
+ * Punct-only (sigil) routes are reserved for Malloy's own use. This is the
+ * closed, enumerated set the compiler claims; any other punct-only routing
+ * warns `reserved-route`. The set being closed is what makes the warning
+ * possible — the compiler knows its own complete sigil vocabulary.
+ */
+const CLAIMED_SIGILS = new Set(['!', '@', '"', ':']);
+/** Bracket pairs an app route may use, as [open, close] — the single source. */
+const BRACKET_PAIRS = [
+    ['(', ')'],
+    ['<', '>'],
+    ['[', ']'],
+    ['{', '}'],
+];
+/** Two views of BRACKET_PAIRS: open->close for lookup, all halves for membership. */
+const OPEN_TO_CLOSE = new Map(BRACKET_PAIRS);
+const BRACKETS = new Set(BRACKET_PAIRS.flat());
+/** Letter, number, or underscore — the "word" characters. */
+const WORDISH = /[\p{L}\p{N}_]/u;
+/**
+ * Parse the leading prefix of a captured annotation.
+ *
+ * `text` is the entire annotation as the lexer captured it, marker included: a
+ * single line `#... content`, or a block `#|...\n<body>` whose body the lexer
+ * has already de-indented and whose closer it has removed. This routine never
+ * parses the content — it returns where the content begins.
+ *
+ * The prefix runs from the marker to the **first whitespace**; that boundary
+ * never moves (no bracket or quote changes it, so a route can never contain
+ * whitespace). After stripping the sigil (`^##?\|?`), the routing matches one
+ * of three forms:
+ *
+ *   1. empty                 -> route `''`        (MOTLY, the human default)
+ *   2. PUNCT+ (no bracket)   -> sigil route       (reserved; unclaimed warns)
+ *   3. OPEN ... CLOSE        -> route = bracketed text (opaque app route)
+ *
+ * Anything else is `malformed-route`. Bracket pairs are `()`, `<>`, `[]`, `{}`;
+ * the route is everything up to the matching close (first close wins, no
+ * nesting), taken literally — no character classification, so `#(bar-chart)`,
+ * `#(https://x/y)`, and `#(v1.2.3)` are all just their bracketed text.
+ */
+function parsePrefix(text) {
+    // 1. Split prefix from content at the first whitespace. The single separator
+    //    character is excluded from the content.
+    //    `\r` is in the class because Windows line endings put a `\r` right before
+    //    the `\n` at every line end (the lexer keeps `\r` out of line *content*),
+    //    so on a content-less prefix like `#(docs)\r\n` the `\r` must not be pulled
+    //    into the routing. We split on it rather than mutating the text, so source
+    //    offsets stay intact for error mapping; any line-ending bytes remain in the
+    //    content, which is faithful to source and harmless to payload parsers.
+    const boundary = text.search(/[ \t\r\n]/);
+    const prefix = boundary === -1 ? text : text.slice(0, boundary);
+    const contentIndex = boundary === -1 ? text.length : boundary + 1;
+    // 2. Strip the sigil: one or two '#', then an optional block '|'.
+    const sigil = /^(#{1,2})(\|?)/.exec(prefix);
+    if (!sigil) {
+        // A captured annotation always starts with '#'; if it somehow does not,
+        // there is no route to speak of — likely a compiler bug upstream.
+        return { route: prefix, contentIndex, malformation: 'malformed-route' };
+    }
+    const routing = prefix.slice(sigil[0].length);
+    // Form 1: empty routing -> the MOTLY namespace.
+    if (routing === '') {
+        return { route: '', contentIndex };
+    }
+    // Form 3: opens with a bracket -> route is the text up to the matching close.
+    // A non-undefined close both proves routing[0] is an open bracket and gives
+    // us its partner in one lookup.
+    const close = OPEN_TO_CLOSE.get(routing[0]);
+    if (close !== undefined) {
+        const closeIdx = routing.indexOf(close, 1);
+        const malformed = closeIdx === -1 || // unclosed
+            closeIdx !== routing.length - 1 || // trailing junk after the close
+            closeIdx === 1; // empty bracketed text: `#()`
+        if (malformed) {
+            return { route: routing, contentIndex, malformation: 'malformed-route' };
+        }
+        return { route: routing.slice(1, closeIdx), contentIndex };
+    }
+    // Form 2: pure punctuation (no word chars, no brackets) -> sigil route.
+    const isPurePunct = [...routing].every(c => !WORDISH.test(c) && !BRACKETS.has(c));
+    if (isPurePunct) {
+        return {
+            route: routing,
+            contentIndex,
+            malformation: CLAIMED_SIGILS.has(routing) ? undefined : 'reserved-route',
+        };
+    }
+    // Otherwise: a bare word, or mixed text with no brackets.
+    return { route: routing, contentIndex, malformation: 'malformed-route' };
+}
+//# sourceMappingURL=prefix.js.map

package/dist/taggable.d.ts

@@ -1,10 +1,26 @@
-import type { TagParseSpec, MalloyTagParse } from './annotation';
+import type { TagParseSpec, MalloyTagParse, Annotations } from './annotation';
 /**
  * Interface for objects that have Malloy tag annotations.
  * This is part of the runtime API - objects returned from the Malloy
  * runtime implement this interface to expose their tag metadata.
  */
 export interface Taggable {
+    /**
+     * Route-aware annotation access — read annotations by *route*. See
+     * `Annotations` for what a route is and which ones are claimed. Unlike
+     * `tagParse`/`getTaglines`, this sees block annotations (`#|`…`|#`).
+     */
+    readonly annotations: Annotations;
+    /**
+     * @deprecated The RegExp form cannot see block annotations (`#|`…`|#`) and
+     * cannot report content offsets for error mapping. Use
+     * `annotations.parseAsTag(route)` instead.
+     */
     tagParse: (spec?: TagParseSpec) => MalloyTagParse;
+    /**
+     * @deprecated The RegExp form cannot see block annotations. Use
+     * `annotations.texts(route)` (raw strings) or `annotations.forRoute(route)`
+     * (objects with offsets) instead.
+     */
     getTaglines: (prefix?: RegExp) => string[];
 }

package/dist/test/resultMatchers.js

@@ -70,7 +70,8 @@ async function runQueryInternal(tm, src) {
     let queryTestTag = undefined;
     try {
         query = tm.model.loadQuery(src);
-        const queryTags = (await query.getPreparedQuery()).tagParse().tag;
+        const queryTags = (await query.getPreparedQuery()).annotations.parseAsTag()
+            .tag;
         queryTestTag = queryTags.tag('test');
     }
     catch (e) {

package/dist/to_stable.d.ts

@@ -1,8 +1,14 @@
 import * as Malloy from '@malloydata/malloy-interfaces';
-import type { FieldDef, ModelDef, ResultStructMetadataDef, SourceDef } from './model';
+import type { Annotation, FieldDef, ModelDef, ResultStructMetadataDef, SourceDef } from './model';
 import { Tag } from '@malloydata/malloy-tag';
 export declare function sourceDefToSourceInfo(sourceDef: SourceDef): Malloy.SourceInfo;
 export declare function modelDefToModelInfo(modelDef: ModelDef): Malloy.ModelInfo;
+/**
+ * IR annotation → stable `Malloy.Annotation[]` shape used across `to_stable`
+ * and the api surfaces. The stable shape carries the raw annotation strings;
+ * routes are derivable at the consumer via `parsePrefix` (`./prefix.ts`).
+ */
+export declare function toStableAnnotations(annot: Annotation | undefined): Malloy.Annotation[];
 export declare function convertFieldInfos(source: SourceDef, fields: FieldDef[]): Malloy.FieldInfo[];
 export declare function writeLiteralToTag(tag: Tag, path: (string | number)[], literal: Malloy.LiteralValue): void;
 export declare function getResultStructMetadataAnnotation(field: SourceDef, resultMetadata: ResultStructMetadataDef): Malloy.Annotation | undefined;

package/dist/to_stable.js

@@ -41,6 +41,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sourceDefToSourceInfo = sourceDefToSourceInfo;
 exports.modelDefToModelInfo = modelDefToModelInfo;
+exports.toStableAnnotations = toStableAnnotations;
 exports.convertFieldInfos = convertFieldInfos;
 exports.writeLiteralToTag = writeLiteralToTag;
 exports.getResultStructMetadataAnnotation = getResultStructMetadataAnnotation;
@@ -77,7 +78,7 @@ function sourceDefToSourceInfo(sourceDef) {
             fields: convertFieldInfos(sourceDef, sourceDef.fields),
         },
         parameters,
-        annotations: getAnnotationsFromField(sourceDef),
+        annotations: toStableAnnotations(sourceDef.annotation),
     };
     return sourceInfo;
 }
@@ -98,7 +99,7 @@ function modelDefToModelInfo(modelDef) {
         }
         else if (entry.type === 'query') {
             const outputStruct = (0, model_1.getResultStructDefForQuery)(modelDef, entry);
-            const annotations = getAnnotationsFromField(entry);
+            const annotations = toStableAnnotations(entry.annotation);
             const resultMetadataAnnotation = outputStruct.resultMetadata
                 ? getResultStructMetadataAnnotation(outputStruct, outputStruct.resultMetadata)
                 : undefined;
@@ -119,7 +120,7 @@ function modelDefToModelInfo(modelDef) {
     }
     for (const query of modelDef.queryList) {
         const outputStruct = (0, model_1.getResultStructDefForQuery)(modelDef, query);
-        const annotations = getAnnotationsFromField(query);
+        const annotations = toStableAnnotations(query.annotation);
         const resultMetadataAnnotation = outputStruct.resultMetadata
             ? getResultStructMetadataAnnotation(outputStruct, outputStruct.resultMetadata)
             : undefined;
@@ -173,11 +174,13 @@ function convertParameterDefaultValue(value) {
             throw new Error('Invalid parameter default value');
     }
 }
-function getAnnotationsFromField(field) {
-    const taglines = (0, annotation_1.annotationToTaglines)(field.annotation);
-    return taglines.map(tagline => ({
-        value: tagline,
-    }));
+/**
+ * IR annotation → stable `Malloy.Annotation[]` shape used across `to_stable`
+ * and the api surfaces. The stable shape carries the raw annotation strings;
+ * routes are derivable at the consumer via `parsePrefix` (`./prefix.ts`).
+ */
+function toStableAnnotations(annot) {
+    return new annotation_1.Annotations(annot).texts().map(value => ({ value }));
 }
 function convertFieldInfos(source, fields) {
     var _a, _b, _c;
@@ -186,10 +189,7 @@ function convertFieldInfos(source, fields) {
         const isPublic = field.accessModifier === undefined;
         if (!isPublic)
             continue;
-        const taglines = (0, annotation_1.annotationToTaglines)(field.annotation);
-        const rawAnnotations = taglines.map(tagline => ({
-            value: tagline,
-        }));
+        const rawAnnotations = toStableAnnotations(field.annotation);
         const annotations = rawAnnotations.length > 0 ? rawAnnotations : undefined;
         if ((0, model_1.isTurtle)(field)) {
             const outputStruct = (0, model_1.getResultStructDefForView)(source, field);
@@ -452,10 +452,7 @@ function convertRecordType(field) {
                 }
             }
             if (f.annotation) {
-                const taglines = (0, annotation_1.annotationToTaglines)(f.annotation);
-                annotations.push(...taglines.map(tagline => ({
-                    value: tagline,
-                })));
+                annotations.push(...toStableAnnotations(f.annotation));
             }
             if ((0, model_1.isAtomic)(f)) {
                 return {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const MALLOY_VERSION = "0.0.396";
+export declare const MALLOY_VERSION = "0.0.398";

package/dist/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MALLOY_VERSION = void 0;
 // generated with 'generate-version-file' script; do not edit manually
-exports.MALLOY_VERSION = '0.0.396';
+exports.MALLOY_VERSION = '0.0.398';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@malloydata/malloy",
-  "version": "0.0.396",
+  "version": "0.0.398",
   "license": "MIT",
   "exports": {
     ".": "./dist/index.js",
@@ -51,9 +51,9 @@
     "generate-version-file": "VERSION=$(npm pkg get version --workspaces=false | tr -d \\\")\necho \"// generated with 'generate-version-file' script; do not edit manually\\nexport const MALLOY_VERSION = '$VERSION';\" > src/version.ts"
   },
   "dependencies": {
-    "@malloydata/malloy-filter": "0.0.396",
-    "@malloydata/malloy-interfaces": "0.0.396",
-    "@malloydata/malloy-tag": "0.0.396",
+    "@malloydata/malloy-filter": "0.0.398",
+    "@malloydata/malloy-interfaces": "0.0.398",
+    "@malloydata/malloy-tag": "0.0.398",
     "@noble/hashes": "^1.8.0",
     "antlr4ts": "^0.5.0-alpha.4",
     "assert": "^2.0.0",