@nezam.ai/runtime-reflection-js

This package reads the language-neutral reflection.rmeta artifact emitted by the private C reflection writer. It validates the version, bounded sections, string table, indexes, cross-references, and integrity checksum before exposing cached lookup APIs for compiled declarations, types, tables, resources, UI declarations, handlers, fields, attributes, and explicitly requested source locations.

It has no compiler, parser, grammar, AST, database provider, UI policy, or provider-selection dependency. The artifact may be supplied as a Buffer, Uint8Array, ArrayBuffer, or loaded from a file path.

const {loadReflectionArtifactFile} = require('@nezam.ai/runtime-reflection-js');
const reflection = loadReflectionArtifactFile('reflection.rmeta');
const table = reflection.getTable('Orders');

Package-sharded registry

New package-sharded consumers use createReflectionPackageRegistry with an explicit, canonical resolved package-set manifest and either a trusted root or explicit shard/export-index loaders. Every package record requires both artifacts. Registry construction validates only the O(P + D) manifest records and opens neither artifact. Direct lookups open and verify only the named package shard; an external reference opens its target package only when it is resolved.

const {createReflectionPackageRegistry} = require('@nezam.ai/runtime-reflection-js');

const registry = createReflectionPackageRegistry(manifest, {trustedRoot: buildRoot});
const app = await registry.findEntity('[email protected]', 'ui:application:erp');
const properties = await registry.properties(app);

Package and entity handles are registry-owned, frozen (packageSlot, localIndex) identities. Forged or cross-registry handles fail closed. Shards remain fixed-record binary views; entity objects and typed property/reference ranges are materialized only when requested. registry.metrics() reports the manifest package count, shards/export indexes opened, their separate byte counts, validation records visited, and returned records materialized so tests can enforce locality structurally.

Public exports are queried with registry.queryExports. Optional packageIdentity narrows discovery to one package; omitting it queries every verified standalone export index in canonical package order without opening a full shard. Optional kind is the numeric LIR entity kind and optional publicName is an exact canonical name. Each compact index uses binary bounds over deterministic export order.

The UI runtime capability provider is registry-backed and asynchronous:

const {createReflectionPackageProvider} = require('@nezam.ai/runtime-reflection-js');
const provider = createReflectionPackageProvider({registry});
runtime.registerProvider('reflection_metadata', provider);

It accepts only a PackageReflectionRegistry. Catalog and selected-application operations discover public candidates through compact export indexes, then use bounded entity, children, attributes, and properties calls for the requested package records. It never accepts a merged artifact or materializes all package entities as a compatibility path.

New consumers should use the progressive projection operations. They require a qualified generic root and explicit limits; root IDs are stable entity IDs and are never interpreted as UI or business names:

const root = {package_identity: '[email protected]', entity_id: 'ui:application:erp'};

const shell = await provider.operations.native_reflection_public_application_shell(
  root,
  {limit: 64},
);
const form = await provider.operations.native_reflection_public_subtree(
  {package_identity: '[email protected]', entity_id: 'ui:form:erp'},
  {limit: 256, max_depth: 8},
);
const page = await provider.operations.native_reflection_public_children_page(
  root,
  {limit: 64, cursor: shell.next_cursor},
);

The shell and children-page responses contain the root, deterministic parent-index-order child records, and an opaque next_cursor (or null). A cursor is canonical, scoped to its package/root/kind, and cannot be reused for another request. limit, max_depth, unknown roots, unknown cursor fields, malformed cursors, and package-boundary changes fail closed. The runtime enforces a maximum page size of 256 records, subtree size of 4096 records, and subtree depth of 32. Subtree output is explicitly marked truncated when its record limit prevents completing the requested depth. A page materializes only the returned child records; it does not call the eager children() operation.

The package-local shard reader validates sections 12–18 as one required profile, including package identity, all finite typed values, explicit local/external references, contiguous owner/source indexes, string boundaries, target coherence, section ranges, and integrity. The registry additionally checks manifest ABI/path/digest/size contracts and resolves cross-package references without a global merge.

The package exposes no global merge or raw-artifact delivery API. Consumers use the package registry and bounded public projections only; unsupported required inputs fail closed.

For tools that need a stable, JSON-safe view of the artifact, use the shared projection API. Resource properties are redacted by default, including credentials embedded in connection URLs:

const {loadReflectionArtifactFile, projectReflectionMetadata} = require('@nezam.ai/runtime-reflection-js');
const reflection = loadReflectionArtifactFile('reflection.rmeta');
const json = projectReflectionMetadata(reflection);

Pass {redact: false} only for explicitly authorized inspection of trusted artifacts.

The package is intentionally limited to the runtime reader. The private C writer and source-language lowering configuration are not part of the npm package.

Measurement

The reader benchmark reports artifact size, one-time load time, and repeated indexed lookup time for a generated artifact:

node test/benchmark.js /path/to/reflection.rmeta

Use the same generated package and workload when comparing reflection against a legacy metadata path; the benchmark does not retain source or AST state.