@osmix/core 0.2.0 → 0.3.0

package/src/relations.ts

@@ -1,6 +1,7 @@
 import { buildRelationRings } from "@osmix/geo/relation-multipolygon";
 import type { OsmPbfRelation } from "@osmix/pbf";
 import { assertValue } from "@osmix/shared/assert";
+import { BitSet } from "@osmix/shared/bit-set";
 import type { ContentHasher } from "@osmix/shared/content-hasher";
 import type {
   GeoBbox2D,
@@ -23,8 +24,9 @@ import { bboxFromLonLats } from "@osmix/types/utils";
 import Flatbush from "flatbush";
 import { around as geoAround } from "geoflatbush";
 
-import { Entities, type EntitiesTransferables } from "./entities.ts";
+import { Entities, type EntitiesTransferables, isValidSpatialBbox } from "./entities.ts";
 import { type IdOrIndex, Ids } from "./ids.ts";
+import { MAX_RELATION_MEMBERS, MAX_UINT32_OFFSET, assertCapacity } from "./limits.ts";
 import type { Nodes } from "./nodes.ts";
 import type StringTable from "./stringtable.ts";
 import { Tags } from "./tags.ts";
@@ -55,7 +57,7 @@ export class Relations extends Entities<OsmRelation> {
   private stringTable: StringTable;
 
   private memberStart: RTA<Uint32Array>;
-  private memberCount: RTA<Uint16Array>; // Maximum 65,535 members per relation
+  private memberCount: RTA<Uint16Array>; // Maximum MAX_RELATION_MEMBERS (65,535) per relation
 
   // Store the ID of the member because relations have other relations as members.
   private memberRefs: RTA<Float64Array>;
@@ -74,8 +76,9 @@ export class Relations extends Entities<OsmRelation> {
   private nodes: Nodes;
   private ways: Ways;
 
-  // Lazily computed relation way membership. Invalidated whenever relations change.
-  private wayMemberIdsCache: ReadonlySet<number> | null = null;
+  // Lazily computed relation way membership keyed by way index. Invalidated whenever relations
+  // change, and rebuilt if the way count no longer matches.
+  private wayMemberCache: BitSet | null = null;
 
   /**
    * Create a new Relations index.
@@ -114,11 +117,28 @@ export class Relations extends Entities<OsmRelation> {
     this.stringTable = stringTable;
   }
 
+  /** Reject a relation whose member count would wrap `memberCount` or `memberStart`. */
+  private assertMemberCapacity(relationId: number, memberCount: number) {
+    assertCapacity(
+      "relation-members",
+      memberCount,
+      MAX_RELATION_MEMBERS,
+      () => `Relation ${relationId}`,
+    );
+    assertCapacity(
+      "total-relation-members",
+      this.memberRefs.length + memberCount,
+      MAX_UINT32_OFFSET,
+      () => `The dataset (at relation ${relationId})`,
+    );
+  }
+
   /**
    * Add a single relation to the index.
    */
   addRelation(relation: OsmRelation) {
-    this.wayMemberIdsCache = null;
+    this.wayMemberCache = null;
+    this.assertMemberCapacity(relation.id, relation.members.length);
     const relationIndex = this.addEntity(relation.id, relation.tags ?? {});
     this.memberStart.push(this.memberRefs.length);
     this.memberCount.push(relation.members.length);
@@ -138,7 +158,7 @@ export class Relations extends Entities<OsmRelation> {
     blockStringIndexMap: Uint32Array,
     filter?: (relation: OsmRelation) => OsmRelation | null,
   ): number {
-    this.wayMemberIdsCache = null;
+    this.wayMemberCache = null;
     const blockToStringTable = (k: number) => {
       const index = blockStringIndexMap[k];
       if (index === undefined) throw Error("Tag key not found");
@@ -190,6 +210,7 @@ export class Relations extends Entities<OsmRelation> {
           })
         : null;
       if (filter && filteredRelation === null) continue;
+      this.assertMemberCapacity(relation.id, filteredRelation?.members.length ?? memberRefs.length);
       added++;
 
       this.addEntity(relation.id, tagKeys, tagValues);
@@ -221,11 +242,17 @@ export class Relations extends Entities<OsmRelation> {
    * Build the spatial index for relations.
    * Handles nested relations by resolving all descendant nodes and ways.
    * If bbox data already exists (e.g., loaded from storage), reuses it.
+   * Returns the existing index when it is already built.
    */
   buildSpatialIndex() {
     if (!this.nodes.isReady()) throw Error("Node index is not ready.");
     if (!this.ways.isReady()) throw Error("Way index is not ready.");
-    if (this.size === 0) return this.spatialIndex;
+    if (this.spatialIndexBuilt) return this.spatialIndex;
+    if (this.size === 0) {
+      this.spatialIndex = new Flatbush(1, 128, Float64Array, BufferConstructor);
+      this.spatialIndexBuilt = true;
+      return this.spatialIndex;
+    }
     console.time("RelationIndex.buildSpatialIndex");
 
     this.spatialIndex = new Flatbush(this.size, 128, Float64Array, BufferConstructor);
@@ -300,11 +327,12 @@ export class Relations extends Entities<OsmRelation> {
       if (ll) lls.push(ll);
     }
 
-    // Collect coordinates from resolved ways
+    // Collect coordinates from resolved ways. Member ways may reference nodes
+    // outside a referentially incomplete extract, so skip unresolvable refs.
     for (const wayId of resolved.ways) {
       const wayIndex = this.ways.ids.getIndexFromId(wayId);
       if (wayIndex === -1) continue;
-      const wayPositions = this.ways.getCoordinates(wayIndex);
+      const wayPositions = this.ways.getResolvedCoordinates(wayIndex);
       lls.push(...wayPositions);
     }
 
@@ -372,30 +400,35 @@ export class Relations extends Entities<OsmRelation> {
   }
 
   /**
-   * Get all way IDs that are members of relations, including nested relations.
+   * Check whether a way is a member of any relation, including through nested relations.
    * Used to exclude these ways from individual rendering.
+   *
+   * Membership is computed once and cached as one bit per way index. Requires the way ID index.
    */
-  getWayMemberIds(): ReadonlySet<number> {
-    if (this.wayMemberIdsCache !== null) return this.wayMemberIdsCache;
+  isWayMember(wayIndex: number): boolean {
+    return this.getWayMembers().has(wayIndex);
+  }
 
-    const wayIds = new Set<number>();
+  private getWayMembers(): BitSet {
+    if (this.wayMemberCache !== null && this.wayMemberCache.size === this.ways.size) {
+      return this.wayMemberCache;
+    }
+
+    const members = new BitSet(this.ways.size);
+    const getRelation = (relId: number) => {
+      const relIndex = this.ids.getIndexFromId(relId);
+      if (relIndex === -1) return null;
+      return this.getByIndex(relIndex);
+    };
     for (let i = 0; i < this.size; i++) {
-      const relation = this.getByIndex(i);
-      const resolved = resolveRelationMembers(
-        relation,
-        (relId) => {
-          const relIndex = this.ids.getIndexFromId(relId);
-          if (relIndex === -1) return null;
-          return this.getByIndex(relIndex);
-        },
-        10, // max depth
-      );
+      const resolved = resolveRelationMembers(this.getByIndex(i), getRelation, 10);
       for (const wayId of resolved.ways) {
-        wayIds.add(wayId);
+        const wayIndex = this.ways.ids.getIndexFromId(wayId);
+        if (wayIndex !== -1) members.add(wayIndex);
       }
     }
-    this.wayMemberIdsCache = wayIds;
-    return this.wayMemberIdsCache;
+    this.wayMemberCache = members;
+    return members;
   }
 
   /**
@@ -457,7 +490,13 @@ export class Relations extends Entities<OsmRelation> {
    */
   intersects(bbox: GeoBbox2D, filterFn?: (index: number) => boolean): number[] {
     if (this.size === 0) return [];
-    return this.spatialIndex.search(bbox[0], bbox[1], bbox[2], bbox[3], filterFn);
+    // A relation with no resolvable member geometry stores an inverted bbox.
+    // Flatbush's contained-node fast path skips per-leaf intersection tests,
+    // so filter inverted boxes out explicitly.
+    return this.spatialIndex.search(bbox[0], bbox[1], bbox[2], bbox[3], (index, x0, y0, x1, y1) => {
+      if (!isValidSpatialBbox(x0, y0, x1, y1)) return false;
+      return filterFn ? filterFn(index) : true;
+    });
   }
 
   /**
@@ -471,7 +510,15 @@ export class Relations extends Entities<OsmRelation> {
   neighbors(lon: number, lat: number, maxResults?: number, maxDistanceKm?: number): number[] {
     if (this.size === 0) return [];
     // Use geoflatbush for proper geographic distance calculations
-    return geoAround(this.spatialIndex, lon, lat, maxResults, maxDistanceKm);
+    return geoAround(this.spatialIndex, lon, lat, maxResults, maxDistanceKm, (index) => {
+      const offset = index * 4;
+      return isValidSpatialBbox(
+        this.bbox.at(offset),
+        this.bbox.at(offset + 1),
+        this.bbox.at(offset + 2),
+        this.bbox.at(offset + 3),
+      );
+    });
   }
 
   /**
@@ -498,7 +545,7 @@ export class Relations extends Entities<OsmRelation> {
   /**
    * Get the approximate memory requirements for a given number of relations in bytes.
    */
-  static getBytesRequired(count: number) {
+  static getBytesRequired(count: number, memberCount = 0, tagCount = 0) {
     if (count === 0) return 0;
     // Approximate members per relation
     let numNodes = count;
@@ -513,9 +560,12 @@ export class Relations extends Entities<OsmRelation> {
 
     return (
       Ids.getBytesRequired(count) +
-      Tags.getBytesRequired(count) +
+      Tags.getBytesRequired(count, count, tagCount) +
       count * Uint32Array.BYTES_PER_ELEMENT + // memberStart
       count * Uint16Array.BYTES_PER_ELEMENT + // memberCount
+      memberCount * Float64Array.BYTES_PER_ELEMENT + // memberRefs
+      memberCount * Uint8Array.BYTES_PER_ELEMENT + // memberTypes
+      memberCount * Uint32Array.BYTES_PER_ELEMENT + // memberRoles
       count * 4 * Float64Array.BYTES_PER_ELEMENT + // bbox
       spatialIndexBytes
     );

package/src/renumber.ts

@@ -0,0 +1,80 @@
+import { Osm } from "./osm.ts";
+
+/** Old ID → new ID for each renumbered entity, by type. JSON- and structured-clone-safe. */
+export interface OsmIdMap {
+  nodes: Record<number, number>;
+  ways: Record<number, number>;
+  relations: Record<number, number>;
+}
+
+/** New positive IDs for one type's negative IDs, after its highest positive ID, in −1, −2, … order. */
+function positiveIds(ids: { size: number; at(index: number): number }): Map<number, number> {
+  let max = 0;
+  const negative: number[] = [];
+  for (let index = 0; index < ids.size; index++) {
+    const id = ids.at(index);
+    if (id < 0) negative.push(id);
+    else max = Math.max(max, id);
+  }
+  negative.sort((a, b) => b - a);
+  return new Map(negative.map((id, index) => [id, max + index + 1]));
+}
+
+/**
+ * A copy of `osm` whose negative node, way and relation IDs are replaced by positive ones, for
+ * tools that reject negative IDs. In OSM files a negative ID conventionally marks a new, not yet
+ * uploaded entity, so only do this when the consumer needs it. Each type gets IDs after its own
+ * highest positive ID, in −1, −2, … order, so the result is deterministic. Way refs and relation
+ * members follow. `osm` is unchanged; the copy has its indexes built.
+ */
+export function renumberNegativeIds(osm: Osm, options: { id?: string } = {}) {
+  const nodeIds = positiveIds(osm.nodes.ids);
+  const wayIds = positiveIds(osm.ways.ids);
+  const relationIds = positiveIds(osm.relations.ids);
+  const mapped = { node: nodeIds, way: wayIds, relation: relationIds } as const;
+  const renumbered = new Osm({ id: options.id ?? osm.id, header: osm.header });
+  for (const node of osm.nodes.sorted()) {
+    renumbered.nodes.addNode({ ...node, id: nodeIds.get(node.id) ?? node.id });
+  }
+  for (const way of osm.ways.sorted()) {
+    renumbered.ways.addWay({
+      ...way,
+      id: wayIds.get(way.id) ?? way.id,
+      refs: way.refs.map((ref) => nodeIds.get(ref) ?? ref),
+    });
+  }
+  for (const relation of osm.relations.sorted()) {
+    renumbered.relations.addRelation({
+      ...relation,
+      id: relationIds.get(relation.id) ?? relation.id,
+      members: relation.members.map((member) => ({
+        ...member,
+        ref: mapped[member.type].get(member.ref) ?? member.ref,
+      })),
+    });
+  }
+  renumbered.buildIndexes();
+  renumbered.buildSpatialIndexes();
+  return { osm: renumbered, idMap: toIdMap(nodeIds, wayIds, relationIds) };
+}
+
+function toIdMap(
+  nodes: Map<number, number>,
+  ways: Map<number, number>,
+  relations: Map<number, number>,
+): OsmIdMap {
+  return {
+    nodes: Object.fromEntries(nodes),
+    ways: Object.fromEntries(ways),
+    relations: Object.fromEntries(relations),
+  };
+}
+
+/** The ID map `renumberNegativeIds(osm)` would apply, without copying the data. */
+export function negativeIdMap(osm: Osm): OsmIdMap {
+  return toIdMap(
+    positiveIds(osm.nodes.ids),
+    positiveIds(osm.ways.ids),
+    positiveIds(osm.relations.ids),
+  );
+}

package/src/stringtable.ts

@@ -10,6 +10,7 @@
 import type { OsmPbfStringTable } from "@osmix/pbf";
 import type { ContentHasher } from "@osmix/shared/content-hasher";
 
+import { MAX_STRING_BYTES, MAX_UINT32_OFFSET, assertCapacity } from "./limits.ts";
 import { type BufferType, ResizeableTypedArray as RTA } from "./typed-arrays.ts";
 
 /**
@@ -27,7 +28,8 @@ export interface StringTableTransferables<T extends BufferType = BufferType> {
 /**
  * Append-only deduplicated string table.
  *
- * Limits: Max string length 65,535 bytes.
+ * Limits: a string holds at most `MAX_STRING_BYTES` (65,535) UTF-8 bytes, and the table
+ * holds at most `MAX_UINT32_OFFSET` bytes in total. Larger input throws `OsmCapacityError`.
  * Rebuilds reverse index lazily after transfer.
  */
 export default class StringTable {
@@ -83,6 +85,18 @@ export default class StringTable {
     if (existingIndex !== undefined) return existingIndex;
     const startIndex = this.start.length;
     const encoded = this.enc.encode(str);
+    assertCapacity(
+      "string-bytes",
+      encoded.length,
+      MAX_STRING_BYTES,
+      () => `String "${str.slice(0, 40)}…"`,
+    );
+    assertCapacity(
+      "total-string-bytes",
+      this.bytes.length + encoded.length,
+      MAX_UINT32_OFFSET,
+      () => "The string table",
+    );
     this.start.push(this.bytes.length);
     this.bytes.pushMany(encoded);
     this.count.push(encoded.length);

package/src/tags.ts

@@ -12,16 +12,23 @@ import type { ContentHasher } from "@osmix/shared/content-hasher";
 import type { OsmTags } from "@osmix/types";
 
 import StringTable from "./stringtable.ts";
-import { type BufferType, ResizeableTypedArray as RTA } from "./typed-arrays.ts";
+import { BufferConstructor, type BufferType, ResizeableTypedArray as RTA } from "./typed-arrays.ts";
+
+const TAG_RANK_BLOCK_SIZE = 256;
+const TAG_BITS_PER_WORD = 32;
 
 /**
  * Serializable state for worker transfer.
  */
 export interface TagsTransferables<T extends BufferType = BufferType> {
-  /** Maps entity index → start position in tagKeys/tagVals. */
-  tagStart: T;
-  /** Maps entity index → number of tags. */
-  tagCount: T;
+  /** Exact number of entities represented by this tag index. */
+  tagEntityCount: number;
+  /** One presence bit per entity. */
+  taggedEntityBits: T;
+  /** Tagged-entity prefix count at each 256-entity boundary. */
+  tagRankCheckpoints: T;
+  /** Tag offsets for tagged entities, including a final sentinel. */
+  tagOffsets: T;
   /** Flattened tag key indices. */
   tagKeys: T;
   /** Flattened tag value indices. */
@@ -38,7 +45,6 @@ export interface TagsTransferables<T extends BufferType = BufferType> {
 /**
  * Bidirectional tag storage.
  *
- * Limits: Max 255 tags per entity.
  * Note: String indices reference a shared `StringTable`.
  */
 export class Tags {
@@ -46,10 +52,14 @@ export class Tags {
   private stringTable: StringTable = new StringTable();
 
   // ─── Entity → Tag Lookup ───────────────────────────────────────────────────
-  /** Maps entity index → start position in tagKeys/tagVals */
-  private tagStart: RTA<Uint32Array>;
-  /** Maps entity index → number of tags (max 255) */
-  private tagCount: RTA<Uint8Array>;
+  /** Exact number of entities represented by this tag index. */
+  private entityCount = 0;
+  /** One presence bit per entity. */
+  private taggedEntityBits: Uint32Array;
+  /** Tagged-entity prefix count at each 256-entity boundary. */
+  private tagRankCheckpoints: Uint32Array;
+  /** Tag offsets for tagged entities, including a final sentinel. */
+  private tagOffsets: RTA<Uint32Array>;
   /** All tag key string indices, concatenated */
   private tagKeys: RTA<Uint32Array>;
   /** All tag value string indices, concatenated (parallel to tagKeys) */
@@ -73,6 +83,12 @@ export class Tags {
    */
   private keyEntityIndexBuilder = new Map<number, number[]>();
 
+  /** Tagged entity indexes collected during ingestion and released on finalization. */
+  private taggedEntityIndexBuilder: RTA<Uint32Array> | null;
+
+  /** Largest tagged entity index seen so far; enforces ascending ingestion order. */
+  private lastTaggedEntityIndex = -1;
+
   /** Whether buildIndex() has been called */
   private indexBuilt = false;
 
@@ -82,22 +98,27 @@ export class Tags {
   constructor(stringTable: StringTable, transferables?: TagsTransferables) {
     this.stringTable = stringTable;
     if (transferables) {
-      this.tagStart = RTA.from(Uint32Array, transferables.tagStart);
-      this.tagCount = RTA.from(Uint8Array, transferables.tagCount);
+      this.entityCount = transferables.tagEntityCount;
+      this.taggedEntityBits = new Uint32Array(transferables.taggedEntityBits);
+      this.tagRankCheckpoints = new Uint32Array(transferables.tagRankCheckpoints);
+      this.tagOffsets = RTA.from(Uint32Array, transferables.tagOffsets);
       this.tagKeys = RTA.from(Uint32Array, transferables.tagKeys);
       this.tagVals = RTA.from(Uint32Array, transferables.tagVals);
       this.keyEntities = RTA.from(Uint32Array, transferables.keyEntities);
       this.keyIndexStart = RTA.from(Uint32Array, transferables.keyIndexStart);
       this.keyIndexCount = RTA.from(Uint32Array, transferables.keyIndexCount);
+      this.taggedEntityIndexBuilder = null;
       this.indexBuilt = true;
     } else {
-      this.tagStart = new RTA(Uint32Array);
-      this.tagCount = new RTA(Uint8Array);
+      this.taggedEntityBits = new Uint32Array(new BufferConstructor(0));
+      this.tagRankCheckpoints = new Uint32Array(new BufferConstructor(0));
+      this.tagOffsets = new RTA(Uint32Array);
       this.tagKeys = new RTA(Uint32Array);
       this.tagVals = new RTA(Uint32Array);
       this.keyEntities = new RTA(Uint32Array);
       this.keyIndexStart = new RTA(Uint32Array);
       this.keyIndexCount = new RTA(Uint32Array);
+      this.taggedEntityIndexBuilder = new RTA(Uint32Array);
     }
   }
 
@@ -122,10 +143,28 @@ export class Tags {
 
   /**
    * Add tags to an entity using key and value indexes.
+   *
+   * Tagged entities must be added in strictly ascending entity-index order and
+   * at most once per entity: the rank/popcount lookup orders tagged entities by
+   * index while `tagOffsets` records them in call order, so an out-of-order or
+   * repeated tagged index would silently misalign every later entity's tags.
+   * `Entities.addEntity` (append-only) satisfies this naturally.
    */
   addTagKeysAndValues(index: number, keys: number[], values: number[]) {
-    this.tagStart.set(index, this.tagKeys.length);
-    this.tagCount.set(index, keys.length);
+    if (this.indexBuilt) throw Error("Tag index already built.");
+    if (keys.length !== values.length) throw Error("Tag keys and values must have equal length.");
+    if (index < 0) throw Error(`Invalid entity index: ${index}`);
+    this.entityCount = Math.max(this.entityCount, index + 1);
+    if (keys.length === 0) return;
+
+    if (index <= this.lastTaggedEntityIndex) {
+      throw Error(
+        `Tagged entity ${index} added out of order (last tagged entity: ${this.lastTaggedEntityIndex}). Tagged entities must be added once, in ascending index order.`,
+      );
+    }
+    this.lastTaggedEntityIndex = index;
+    this.taggedEntityIndexBuilder?.push(index);
+    this.tagOffsets.push(this.tagKeys.length);
     this.tagKeys.pushMany(keys);
     this.tagVals.pushMany(values);
 
@@ -146,8 +185,39 @@ export class Tags {
    * Must be called before `hasKey()`.
    */
   buildIndex() {
-    this.tagStart.compact();
-    this.tagCount.compact();
+    if (this.indexBuilt) return;
+
+    const taggedEntityIndexes = this.taggedEntityIndexBuilder;
+    if (!taggedEntityIndexes) throw Error("Tagged entity builder is unavailable.");
+    const bitWordCount = Math.ceil(this.entityCount / TAG_BITS_PER_WORD);
+    this.taggedEntityBits = new Uint32Array(
+      new BufferConstructor(bitWordCount * Uint32Array.BYTES_PER_ELEMENT),
+    );
+    for (let i = 0; i < taggedEntityIndexes.length; i++) {
+      const entityIndex = taggedEntityIndexes.at(i);
+      const wordIndex = entityIndex >>> 5;
+      this.taggedEntityBits[wordIndex] =
+        (this.taggedEntityBits[wordIndex] ?? 0) | (1 << (entityIndex & 31));
+    }
+
+    const checkpointCount = Math.ceil(this.entityCount / TAG_RANK_BLOCK_SIZE) + 1;
+    this.tagRankCheckpoints = new Uint32Array(
+      new BufferConstructor(checkpointCount * Uint32Array.BYTES_PER_ELEMENT),
+    );
+    let taggedIndex = 0;
+    for (let checkpoint = 0; checkpoint < checkpointCount; checkpoint++) {
+      const entityBoundary = checkpoint * TAG_RANK_BLOCK_SIZE;
+      while (
+        taggedIndex < taggedEntityIndexes.length &&
+        taggedEntityIndexes.at(taggedIndex) < entityBoundary
+      ) {
+        taggedIndex++;
+      }
+      this.tagRankCheckpoints[checkpoint] = taggedIndex;
+    }
+
+    this.tagOffsets.push(this.tagKeys.length);
+    this.tagOffsets.compact();
     this.tagKeys.compact();
     this.tagVals.compact();
 
@@ -158,9 +228,11 @@ export class Tags {
       this.keyEntities.pushMany(entityIndexes);
     }
 
+    this.keyEntities.compact();
     this.keyIndexStart.compact();
     this.keyIndexCount.compact();
     this.keyEntityIndexBuilder.clear();
+    this.taggedEntityIndexBuilder = null;
 
     this.indexBuilt = true;
   }
@@ -176,16 +248,41 @@ export class Tags {
    * Get the number of tags for an entity.
    */
   cardinality(index: number): number {
-    return this.tagCount.at(index) ?? 0;
+    const taggedIndex = this.getTaggedEntityIndex(index);
+    if (taggedIndex === -1) return 0;
+    return this.tagOffsets.at(taggedIndex + 1) - this.tagOffsets.at(taggedIndex);
+  }
+
+  /** Number of entities that have at least one tag. */
+  get taggedEntityCount(): number {
+    return this.indexBuilt
+      ? Math.max(0, this.tagOffsets.length - 1)
+      : (this.taggedEntityIndexBuilder?.length ?? 0);
+  }
+
+  /** Iterate tagged entity indexes without allocating an intermediate array. */
+  *taggedEntityIndexes(): Generator<number> {
+    if (!this.indexBuilt) throw Error("Tag index not built.");
+    for (let wordIndex = 0; wordIndex < this.taggedEntityBits.length; wordIndex++) {
+      let word = this.taggedEntityBits[wordIndex] ?? 0;
+      while (word !== 0) {
+        const lowestBit = word & -word;
+        const bit = 31 - Math.clz32(lowestBit);
+        const entityIndex = wordIndex * TAG_BITS_PER_WORD + bit;
+        if (entityIndex < this.entityCount) yield entityIndex;
+        word = (word & (word - 1)) >>> 0;
+      }
+    }
   }
 
   /**
    * Get the tags for an entity.
    */
   getTags(index: number): OsmTags | undefined {
-    const tagCount = this.tagCount.at(index) ?? 0;
-    if (tagCount === 0) return;
-    const tagStart = this.tagStart.at(index) ?? 0;
+    const taggedIndex = this.getTaggedEntityIndex(index);
+    if (taggedIndex === -1) return;
+    const tagStart = this.tagOffsets.at(taggedIndex);
+    const tagCount = this.tagOffsets.at(taggedIndex + 1) - tagStart;
     const tagKeyIndexes = this.tagKeys.array.slice(tagStart, tagStart + tagCount);
     const tagValIndexes = this.tagVals.array.slice(tagStart, tagStart + tagCount);
     const tags: OsmTags = {};
@@ -225,7 +322,12 @@ export class Tags {
    * Get all entity indexes that have a specific tag key.
    */
   hasKey(keyIndex: number): number[] {
-    if (keyIndex < 0) return [];
+    if (
+      keyIndex < 0 ||
+      keyIndex >= this.keyIndexStart.length ||
+      keyIndex >= this.keyIndexCount.length
+    )
+      return [];
     const start = this.keyIndexStart.at(keyIndex) ?? 0;
     const count = this.keyIndexCount.at(keyIndex) ?? 0;
     return Array.from(this.keyEntities.array.subarray(start, start + count));
@@ -245,8 +347,10 @@ export class Tags {
    */
   transferables(): TagsTransferables {
     return {
-      tagStart: this.tagStart.array.buffer,
-      tagCount: this.tagCount.array.buffer,
+      tagEntityCount: this.entityCount,
+      taggedEntityBits: this.taggedEntityBits.buffer,
+      tagRankCheckpoints: this.tagRankCheckpoints.buffer,
+      tagOffsets: this.tagOffsets.array.buffer,
       tagKeys: this.tagKeys.array.buffer,
       tagVals: this.tagVals.array.buffer,
       keyEntities: this.keyEntities.array.buffer,
@@ -256,12 +360,17 @@ export class Tags {
   }
 
   /**
-   * Get the approximate memory requirements for a given number of tags in bytes.
+   * Get the approximate memory requirements for a tag index in bytes.
+   *
+   * @param tagCount - Total key/value pairs. Each costs 12 bytes: key, value and the
+   * reverse key → entity index. The small per-key index arrays are not counted.
    */
-  static getBytesRequired(count: number) {
+  static getBytesRequired(entityCount: number, taggedEntityCount = entityCount, tagCount = 0) {
     return (
-      count * Uint32Array.BYTES_PER_ELEMENT + // tagStart
-      count * Uint8Array.BYTES_PER_ELEMENT // tagCount
+      Math.ceil(entityCount / TAG_BITS_PER_WORD) * Uint32Array.BYTES_PER_ELEMENT +
+      (Math.ceil(entityCount / TAG_RANK_BLOCK_SIZE) + 1) * Uint32Array.BYTES_PER_ELEMENT +
+      (taggedEntityCount + 1) * Uint32Array.BYTES_PER_ELEMENT +
+      tagCount * 3 * Uint32Array.BYTES_PER_ELEMENT // tagKeys + tagVals + keyEntities
     );
   }
 
@@ -280,9 +389,42 @@ export class Tags {
    */
   updateHash(hasher: ContentHasher): ContentHasher {
     return hasher
-      .update(this.tagStart.array)
-      .update(this.tagCount.array)
+      .updateNumber(this.entityCount)
+      .update(this.taggedEntityBits)
+      .update(this.tagOffsets.array)
       .update(this.tagKeys.array)
       .update(this.tagVals.array);
   }
+
+  /**
+   * Return the compact tagged-entity ordinal, or -1 when the entity has no tags.
+   *
+   * The ordinal is the entity's rank among tagged entities: read the cached
+   * prefix count at the nearest 256-entity checkpoint, popcount the presence
+   * words between the checkpoint and the entity's word, then popcount the bits
+   * below the entity within its own word. The result indexes `tagOffsets`.
+   */
+  private getTaggedEntityIndex(index: number): number {
+    if (index < 0 || index >= this.entityCount) return -1;
+    const wordIndex = index >>> 5;
+    const word = this.taggedEntityBits[wordIndex] ?? 0;
+    const bit = index & 31;
+    if ((word & (1 << bit)) === 0) return -1;
+
+    const checkpoint = index >>> 8;
+    let rank = this.tagRankCheckpoints[checkpoint] ?? 0;
+    const checkpointWord = checkpoint * (TAG_RANK_BLOCK_SIZE / TAG_BITS_PER_WORD);
+    for (let i = checkpointWord; i < wordIndex; i++) {
+      rank += popcount(this.taggedEntityBits[i] ?? 0);
+    }
+    const lowerBitMask = bit === 0 ? 0 : 0xffffffff >>> (TAG_BITS_PER_WORD - bit);
+    return rank + popcount(word & lowerBitMask);
+  }
+}
+
+/** Count set bits in an unsigned 32-bit integer. */
+function popcount(value: number): number {
+  const pairs = value - ((value >>> 1) & 0x55555555);
+  const nibbles = (pairs & 0x33333333) + ((pairs >>> 2) & 0x33333333);
+  return (((nibbles + (nibbles >>> 4)) & 0x0f0f0f0f) * 0x01010101) >>> 24;
 }