A Logos vocabulary is a local map from compact intent references to allowed contexts, required parameters, required proofs, and handler names. The beta SDK keeps this map inside the runtime that is about to act.

Resolution Principle

The platform can help publish and review vocabularies later, but execution should not fetch new meaning at the moment of action. Register vocabularies at startup, freeze published versions, and only dispatch after local verification passes.

Vocabulary Shape

The SDK compiles readable .logos files into this canonical structure. Intent ids are compact; handler names stay local.

canonical vocabulary

typescript

type Vocabulary = {
  version: string;
  intents: {
    id: number;
    name: string;
    code?: string;
    riskLevel: 1 | 2 | 3 | 4 | 5;
    allowedContexts?: string[];
    parameterKeys?: string[];
    requiredProofs?: string[];
    handler: string;
  }[];
};

Register at Startup

Register the vocabulary before the agent, gateway, or API worker accepts protected actions. Unknown versions and duplicate ids fail closed.

compile and register

typescript

import { compileLogos, LogosLexicon } from "@silentauth/logos-lexicon";

const { vocabulary } = compileLogos(`
  vocabulary silentauth.infra.v1

  intent CSIV_INFRA_001 infra.deploy {
    risk: 4
    context: ci_cd
    params: service, environment, commit
    proofs: maintainer_approval
    handler: deployments.release
  }
`);

const lexicon = new LogosLexicon();
lexicon.registerVocabulary(vocabulary);

cli helpers

bash

logos compile examples/infra-deploy.logos --out infra.vocabulary.json
logos types examples/infra-deploy.logos --out infra.helpers.ts

Dispatch Local Handlers

Logos returns a handler name only after signature, expiry, vocabulary, context, parameter, and proof checks pass. Your application still owns the actual execution.

local handler dispatch

typescript

const handlers = {
  "deployments.release": async (params) => {
    await deploy(params.service, params.environment, params.commit);
  }
};

const checked = await lexicon.verifyAndResolve(signed, {
  secret: process.env.LOGOS_HS256_SECRET!,
  resolution: {
    context: "ci_cd",
    satisfiedProofs: ["maintainer_approval"]
  }
});

if (!checked.ok) throw new Error(checked.reason);

await handlers[checked.resolved.handler](checked.token.params);

Versioning Rules

Freeze published meaning

Do not change what CSIV_INFRA_001 means after clients receive it. Publish a new vocabulary version instead.

Keep secrets out of vocabularies

Vocabularies describe intent and handlers. Signing secrets stay in the server or gateway key store.

Proof names are inputs

VINAC-FM, QR, NFC, or human approval appear as satisfiedProofs. Logos does not collect proof by itself.

Handlers are local

A handler string should resolve inside your runtime. The token never carries executable code.

Verify and Resolve

The fail-closed execution boundary

SDK Guide

Compile, sign, validate, and map tool calls