@kneelinghorse/semantic-protocol

Zero-dependency semantic manifest protocol with deterministic URNs, stable hashing, graph edges, validation, and catalog search.

npm install @kneelinghorse/semantic-protocol

const {
  createSemanticProtocol,
  createSemanticCatalog
} = require('@kneelinghorse/semantic-protocol');

const accountProfile = createSemanticProtocol({
  id: 'account-profile',
  element: { type: 'api', name: 'Get Account' },
  semantics: {
    purpose: 'read account profile',
    tags: ['account', 'profile']
  },
  context: {
    domain: 'identity',
    protocolBindings: {
      api: ['urn:proto:api:[email protected]']
    }
  }
});

console.log(accountProfile.manifest().urn);
console.log(accountProfile.validate().ok);

const catalog = createSemanticCatalog([accountProfile]);
console.log(catalog.search({ text: 'account profile', limit: 1 }));

What It Provides

• Deterministic semantic manifests with generated urn:proto:semantic:*@3.3.1 identifiers.
• Stable hashes for node, graph, text, vector, and signature comparison.
• Cross-protocol bindings that become graph edges.
• Built-in validators for core shape, bindings, graph edges, and vectors.
• Lightweight query expressions for equality, containment, existence, regex, membership, and numeric comparison.
• Catalog search that blends lexical matching, deterministic fallback vectors, and graph proximity.

API

const {
  SEMANTIC_PROTOCOL_VERSION,
  SemanticProtocolV33,
  createSemanticProtocol,
  createSemanticCatalog
} = require('@kneelinghorse/semantic-protocol');

createSemanticProtocol(manifest, options)

Returns an immutable protocol wrapper:

• version()
• manifest()
• validate(names?)
• query(expr) / match(expr)
• diff(other)
• generateDocs()
• toGraph(options?)
• set(path, value)

createSemanticCatalog(items, options)

Returns a catalog wrapper:

• items()
• get(urn)
• find(predicateOrExpr)
• search(options)
• neighbors(urn, options?)
• traverse(starts, options?)
• shortestPath(from, to, options?)
• exportGraph(options?)

Query Examples

protocol.query('element.intent:=:"Read"');
protocol.query('semantics.tags:has:profile');
protocol.query('context.domain:exists');
protocol.query('element.criticality:>=:5');
protocol.query('semantics.purpose:regex:/account/i');

URN Shape

Semantic manifests default to:

urn:proto:semantic:{id}@{version}

Cross-protocol bindings may point at any URN, including versioned and fragmented protocol URNs:

urn:proto:api:[email protected]
urn:proto:docs:[email protected]#get-account

Runtime

• CommonJS package.
• Zero runtime dependencies.
• Requires Node.js 18 or newer.
• Uses BigInt for deterministic FNV-1a hashing.

Release Check

npm test
npm pack --dry-run