@teqfw/log

Human-governed. Agent-built. Agent-ready.

@teqfw/log gives TeqFW packages one stable way to emit useful log records without coupling to a concrete logging backend. It is a foundational package of the Tequila Framework (TeqFW): created and evolved by coding agents under the architectural direction and final responsibility of Alex Gusev, and shipped with a version-matched Agent Skill so other agents can understand, integrate, and use it correctly.

Why use it

A logging contract lets packages log without binding the application to a logging backend.

Without a common contract, packages either import a concrete logger or invent incompatible local APIs, coupling message emission to a specific runtime policy:

package → logging backend → runtime policy

@teqfw/log keeps the package boundary intact:

package → logging contract → host-selected writers

That enables:

• a backend-neutral logging surface for TeqFW packages;
• source-bound records that identify the responsible component;
• fixed levels: trace, debug, info, warn, error, and fatal;
• structured message + data records, including data.err for caught errors;
• a browser- and Node.js-compatible console reference writer;
• a shared mutable policy with *=info as the out-of-box threshold;
• composition-root control over optional custom writers and their shutdown.

Quick start

Application components receive the provider through TeqFW DI, bind a stable source once, and reuse the returned logger:

export default function Service({logger}) {
  const log = logger.forSource('App_User_Service');

  return {
    async load(userId) {
      log.info('User profile loaded', {userId});
    },
  };
}

export const __deps__ = {
  default: {
    logger: 'TeqFw_Log_Provider$',
  },
};

Public API

• @teqfw/log — the TeqFw_Log_Provider DI component and its public TypeScript-facing contract types.

Do not import @teqfw/log/src/**.

Runtime logging policy

Each Provider shares one TeqFw_Log_Policy$ with all of its bound loggers. The default *=info writes info and more severe events to the built-in console writer. A rule level is a threshold: it enables that level and all more severe levels. The special Policy value none disables every log level for its matching source. Rules must include the * default and may be only:

• * — the default rule;
• an exact TeqFW source such as App_Import_Run;
• a namespace prefix with one trailing *, such as App_Import_*.

The longest literal match wins:

*=info
TeqFw_Db_*=debug
App_Import_*=trace

Disable all logging without creating records or calling the Writer:

*=none

A more specific source rule may re-enable logging, for example App_Import_*=debug.

Inject the shared Policy into a host configuration component and change it explicitly:

export default function LogPolicyConfig({policy}) {
  return {
    configure() {
      policy.setRules({
        '*': 'info',
        'TeqFw_Db_*': 'debug',
        'App_Import_*': 'trace',
      });

      policy.setRule('App_Import_Run', 'debug');
    },
  };
}

export const __deps__ = {
  default: {
    policy: 'TeqFw_Log_Policy$',
  },
};

setRules() atomically replaces the complete rule set; setRule() changes one rule while retaining the others. Existing loggers see updates immediately because they use the same Policy. Logger.isEnabled(level) and actual output always consult it.

For configuration text already held by the host, call policy.applyText(text). For an explicit Node.js file, inject TeqFw_Log_Policy_File$ into a Node-only host component and call await apply(path):

export default function NodeLogPolicyLoader({policyFile}) {
  return {
    async apply() {
      await policyFile.apply('/etc/my-app/log.policy');
    },
  };
}

export const __deps__ = {
  default: {
    policyFile: 'TeqFw_Log_Policy_File$',
  },
};

Policy files use one pattern=level rule per line; blank lines and lines beginning with # are ignored. Invalid syntax, duplicate patterns, missing default rules, invalid patterns, and invalid levels fail without changing the active rules. @teqfw/log never searches for configuration files.

Inject TeqFw_Log_Policy_Factory$ when a host component needs an independent Policy from programmatic rules. It does not automatically replace a Provider's shared Policy; the host decides where that independent instance is used.

Agent-ready package

The package ships with three aligned interfaces:

• runtime code in src;
• type information through JSDoc and types.d.ts;
• a version-matched Agent Skill in skills/teqfw-log.

The skill explains the logging contract, source binding, records, and package boundaries. An agent does not need to reconstruct the package architecture from source code alone.

The package uses @teqfw/di for composition. Project instructions and application architecture remain authoritative over package-level guidance.

Best fit

Use @teqfw/log when TeqFW modules need a durable shared logging contract but the application must retain control over logging infrastructure.

Use a full logging framework directly when an application has no need for a package-level contract or replaceable backend policy.

Add to a project

npm install @teqfw/log

Boundaries

This package is a contract layer with a reference console writer. It does not create a host application's composition root and does not provide transport registries, persistence, configuration DSLs, telemetry integration, or enterprise logging policy.

Agent-Driven Development

TeqFW is built through the same development model that it is designed to enable: one human defines the intent, architecture, constraints, and acceptance criteria; coding agents implement and maintain the products; other agents use those products in different combinations to create applications.

@teqfw/log is a foundational package of TeqFW. The package includes a version-matched Agent Skill in skills/teqfw-log. The README provides a human-facing product overview; the skill provides agents with the package concepts, contracts, integration rules, examples, and boundaries.

Mount the skill into a host project:

mkdir -p .agents/skills
ln -s ../../node_modules/@teqfw/log/skills/teqfw-log \
  .agents/skills/teqfw-log

Each TeqFW package is both a practical software component and a working demonstration of human-governed, agent-driven development. This work follows the Agent-Driven Software Management (ADSM) approach: human intent, architectural authority, acceptance, and responsibility remain authoritative; agents act as implementation and reasoning partners.

• Tequila Framework
• Agent-Driven Software Management: A Practical Guide
• Alex Gusev