The full manifesto is available here: Agentic Engineering Manifesto.

AI agents are changing how we build software, but I do not think the important change is only that code gets written faster.

The bigger change is where engineering judgment moves.

When working with agents, the human role becomes less about typing every line of code and more about shaping the problem, giving useful context, choosing the direction, reviewing the approach, and making sure there is a good feedback loop.

That is why I wrote the Agentic Engineering Manifesto.

The main idea is simple: agents are useful, but they need to be guided in the right way. A good prompt is not just a task description. It should tell the agent where to look, what matters, how to think about the change, and how to verify the result.

I also think codebases now need to be easier for agents to navigate. Names, structure, examples, tests, and discoverable patterns matter more when another participant in the development process is searching and reasoning through the codebase.

Another important shift is refactoring. Since agents can make broad changes more cheaply, we should be more willing to ask whether a feature is hard because the feature is actually hard, or because the current architecture is resisting it.

The manifesto is my attempt to write down these ideas in a small and clear form.

It is not about trusting AI blindly. It is almost the opposite. Agentic engineering needs planning, verification, tests, build output, logs, and review. The better the feedback loop, the more useful the agent becomes.

I see this as an early version of how software teams will work with agents: humans leading design and direction, agents taking more ownership during implementation, and both depending on codebases that are easy to understand, change, and verify.

The full specification is available here: Authorization Model Specification.

Authorization logic often starts simple.

At first, a role like admin, editor, or viewer is enough. Then the product grows. You add organizations, projects, machine clients, service accounts, field-level rules, exceptions, audit logs, and suddenly the question "can this principal do this action?" is answered differently in different parts of the codebase.

This specification is my attempt to make that question explicit, portable, and easy to evaluate.

The goal is not to define authentication, token issuance, identity provisioning, or transport security. Those are separate concerns. This spec focuses only on authorization decisions: how roles, permissions, scopes, and policy evaluation should work together.

The Core Idea

The model is built around a small chain:

Principal -> Role -> Permission -> allow | deny

A principal can be a human user, a service account, or a machine-to-machine client. A role is a named bundle of permission statements, such as auditor, editor, or billing-admin.

Roles are not magical. Their names do not grant authority by themselves. A role only matters because of the permission statements it contains, and a principal only receives authority through an explicit binding:

(principal, role, scope)

This is important because it keeps the model auditable. If someone has access, there should be a concrete binding and a concrete permission statement that explains why.

The Design Principles

The specification is based on five principles:

Default-deny: if nothing explicitly allows an action, the answer is deny.

Deny-overrides: if both an allow and a deny match the same request, the deny wins.

Explicit over implicit: authority is never inferred from role names, group names, or conventions.

Decision and enforcement separation: application code should ask a Policy Decision Point (PDP) for a decision. It should not spread authorization rules across controllers, services, and handlers.

Auditability: decisions should be loggable with enough context to reconstruct what happened.

These principles make the model predictable. There is no hidden privilege, no role-name guessing, and no ambiguous conflict resolution.

Permission Strings

Permission statements are serialized as compact strings:

<organization>:<service>/<resource>[:<field>[:<resource_id>]]/<effect>/<action>

For example:

acme:api/suppliers/allow/update

This means: in the acme organization, for the api service, allow updating suppliers.

The format also supports field-level and instance-level rules:

acme:api/contacts:email/allow/read
acme:api/suppliers:*:12345/deny/read

The first statement allows reading only the email field of contacts. The second denies reading supplier 12345.

Wildcards are supported too:

acme:api/suppliers/allow/*
acme:api/suppliers/deny/delete

Together, these allow every action on suppliers except deletion.

The string format is intentionally compact enough to be transported in places like JWT claims, while still being readable for operators and auditors.

How Evaluation Works

The evaluator receives a request:

(principal, action, resource_uri)

Then it evaluates the principal's effective permission set in three steps.

First, it keeps only the permission statements that match the request. A segment matches if it is exactly equal to the request segment or if it is *.

Second, if any matching statement has effect = deny, the result is deny.

Third, if at least one matching statement has effect = allow and no deny matched, the result is allow. Otherwise, the result is deny.

In pseudocode:

def evaluate(request, permissions):
    applicable = [p for p in permissions if matches(p, request)]

    if any(p.effect == "deny" for p in applicable):
        return Decision.DENY

    if any(p.effect == "allow" for p in applicable):
        return Decision.ALLOW

    return Decision.DENY

One important detail: the evaluator is specificity-agnostic. A specific deny does not beat a wildcard allow because it is more specific. It wins because all denies override all allows.

For example:

acme:api/suppliers/allow/read
acme:api/suppliers:*:12345/deny/read

Reading suppliers is generally allowed, but reading supplier 12345 is denied.

What This Spec Is For

This specification is useful for teams building a Policy Decision Point, integrating a Policy Enforcement Point, or simply trying to make authorization rules easier to audit.

It gives you:

• a portable permission string format

• clear role and binding semantics

• default-deny behavior

• deny-overrides conflict handling

• a small evaluation algorithm

• decision logging requirements

The main benefit is consistency. Instead of each service inventing its own interpretation of roles and permissions, services can ask the same kind of question and receive the same kind of answer.

Authorization should be boring, predictable, and explainable. That is what this spec is designed to support.

You can read the complete spec, including the grammar, validation rules, examples, and versioning notes, at mahdavipanah.github.io/authorization-model.

The this Keyword in JavaScript

In JavaScript, the value of this is determined by how a function is invoked, not where it's defined. When a regular function is called as a method of an object (obj.method()), this refers to that object. However, when a function is invoked standalone (func()), this typically refers to the global object (in non-strict mode) or is undefined (in strict mode) (MDN documentation).

Common Pitfall: Losing the Context

Consider the following example:

class MyClass {
  constructor() {
    this.factor = 2;
  }

  methodA(value) {
    return value * this.factor;
  }

  methodB() {
    return [1, 2, 3, 4].map(function (value) {
      const newValue = value + 1;
      return this.methodA(newValue); // TypeError: Cannot read properties of undefined (reading 'methodA')
    });
  }
}

In this example, the callback passed to map() is a regular function, causing this to be undefined inside it. This results in a runtime error.

Arrow Functions: A Concise Solution

Arrow functions provide a concise syntax and lexically bind this, meaning they inherit this from their surrounding scope (Google JS Style Guide):

class MyClass {
  constructor() {
    this.factor = 2;
  }

  methodA(value) {
    return value * this.factor;
  }

  methodB() {
    return [1, 2, 3, 4].map((value) => {
      const newValue = value + 1;
      return this.methodA(newValue);
    });
  }
}

With arrow functions, the context of this remains bound to the instance of MyClass, preventing the earlier error.

Best Practices

To avoid confusion and potential errors with this, consider these guidelines:

• Prefer Arrow Functions for Nested Functions: Arrow functions simplify the scoping of this in nested functions.

• Avoid Function Expressions for Callbacks: Regular functions can lead to unexpected bindings. Use arrow functions for callbacks.

• Explicit Binding with bind: If using regular functions, explicitly bind this using .bind(this) (MDN bind).

By understanding the behavior of this and utilizing arrow functions appropriately, you can write more predictable and maintainable JavaScript code.

keyv-upstash is a storage adapter for Keyv that connects it to Upstash Redis, a serverless Redis platform. With this adapter, you get a simple, efficient, and flexible solution for key-value storage in serverless applications.

What is Keyv?

Keyv is a versatile key-value storage library that supports multiple backends through adapters. It provides:

• TTL-based Expiry: Ideal for caching or persistent storage.

• Namespace Support: Avoids key collisions in shared environments.

• Extensibility: Easy to build custom modules or add features like compression.

Keyv works with many adapters, such as Redis, SQLite, MongoDB, and now, keyv-upstash for Upstash Redis.

Why keyv-upstash?

keyv-upstash extends Keyv's capabilities by integrating it with Upstash Redis, offering:

1. Serverless Compatibility: Upstash Redis works without managing connections, scaling automatically, perfect for serverless apps.

2. Flexible: Compatible with Keyv’s ecosystem and supports third-party extensions.

3. Cache Layering: Combine with Cacheable for multi-layered caching.

4. No Vendor Lock-In: Is fully compatible with serverless-redis-http so you can setup your own serverless Redis and use this adapter with it.

Getting Started

Follow these steps to integrate keyv-upstash:

1. Install Keyv and keyv-upstash

Install Keyv and the Upstash adapter:

npm install keyv keyv-upstash

Optional: Install Cacheable for layered caching:

npm install cacheable

2. Set Up keyv-upstash

Make sure you have a Redis database created in Upstash. Here’s how to use keyv-upstash in your project:

Basic Usage

import Keyv from 'keyv';
import { KeyvUpstash } from 'keyv-upstash';

const keyv = new Keyv({
  store: new KeyvUpstash({
    url: 'your-upstash-redis-url',
    token: 'your-upstash-redis-token',
  }),
});

// Set a key-value pair
await keyv.set('foo', 'bar');

// Retrieve the value
const value = await keyv.get('foo');
console.log(value); // 'bar'

Using Namespaces

Namespaces prevent key collisions and allow scoped clearing:

const keyv = new Keyv({
  store: new KeyvUpstash({
    url: 'your-upstash-redis-url',
    token: 'your-upstash-redis-token',
    namespace: 'my-namespace',
  }),
});

await keyv.set('foo', 'bar'); // Stored as 'my-namespace::foo'

Cache Layering with Cacheable

Combine keyv-upstash with Cacheable for multi-layer caching:

import { Cacheable } from 'cacheable';

const redisStore = new KeyvUpstash({
  url: 'your-upstash-redis-url',
  token: 'your-upstash-redis-token',
});

const cache = new Cacheable({
  primary: new Map(), // Fast in-memory caching
  secondary: redisStore, // Persistent Redis caching
});

await cache.set('foo', 'bar', { ttl: 1000 }); // Stores in both layers
const value = await cache.get('foo'); // Fast lookup from memory or Redis
console.log(value); // 'bar'

Advanced Features

Batch Operations

Improve performance with setMany and getMany:

await keyv.setMany([
  { key: 'key1', value: 'value1' },
  { key: 'key2', value: 'value2' },
]);

const values = await keyv.getMany(['key1', 'key2']);
console.log(values); // ['value1', 'value2']

Custom Configuration

Customize your setup with options like defaultTtl, keyPrefixSeparator, and clearBatchSize.

This guide is beneficial if you're using Express adapter. For NestJS applications utilizing the Fastify adapter, these links may be helpful:

• https://fastify.dev/docs/latest/Guides/Serverless/#vercel

• https://github.com/vercel/examples/tree/main/starter/fastify

🚀 You can access the complete source code discussed in this article at this GitHub repository: https://github.com/mahdavipanah/nestjs-on-vercel

Vercel's Support for Express Apps

Vercel offers a convenient feature for deploying your Express app by:

1. Exposing the Express app object in an API.

2. Defining a rewrite rule that directs all incoming traffic to this single API.

I followed Vercel’s official guide for deploying Express to deploy NestJS by similarly exposing NestJS’s underlying Express app object.

Step 1 - create a NestJS app

Skip this step if you already have a NestJS app set up.

Install NestJS and create a new app:

nest new my-app

Step 2 - Install Necessary NPM Packages

npm install express @nestjs/platform-express
npm install -D @types/express

Step 3 - Create src/AppFactory.ts file

This file serves as a single module that manages all necessary NestJS app bootstrapping and exports both the NestJS app and its underlying Express app object.

Create a file named AppFactory.ts inside the src directory in your project’s root:

import { ExpressAdapter } from '@nestjs/platform-express';
import { NestFactory } from '@nestjs/core';
import express, { Request, Response } from 'express';
import { Express } from 'express';
import { INestApplication } from '@nestjs/common';
import { AppModule } from './app.module.js';

export class AppFactory {
  static create(): {
    appPromise: Promise<INestApplication<any>>;
    expressApp: Express;
  } {
    const expressApp = express();
    const adapter = new ExpressAdapter(expressApp);
    const appPromise = NestFactory.create(AppModule, adapter);

    appPromise
      .then((app) => {
        // You can add all required app configurations here

        /**
         * Enable cross-origin resource sharing (CORS) to allow resources to be requested from another domain.
         * @see {@link https://docs.nestjs.com/security/cors}
         */
        app.enableCors({
          exposedHeaders: '*',
        });

        app.init();
      })
      .catch((err) => {
        throw err;
      });

    // IMPORTANT This express application-level middleware makes sure the NestJS app is fully initialized
    expressApp.use((req: Request, res: Response, next) => {
      appPromise
        .then(async (app) => {
          await app.init();
          next();
        })
        .catch((err) => next(err));
    });

    return { appPromise, expressApp };
  }
}

Step 4 - Modify src/main.ts File

By default, NestJS has a src/main.ts file that serves as the entry point of the application, including all configuration and bootstrapping. Modify this file to move everything to the AppFactory.ts file, keeping only the invocation of the listen method:

import { AppFactory } from './AppFactory.js';

async function bootstrap() {
  const { appPromise } = AppFactory.create();
  const app = await appPromise;

  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

Step 5 - Add api/index.ts File

By default, the Vercel runtime builds and serves any function created within the /api directory of a project to Vercel (doc). Since Vercel understands and handles the Express app object, create a function inside this directory that exports the Express app object:

/**
 * This file exports Express instance for specifically for the deployment of the app on Vercel.
 */

import { AppFactory } from '../src/AppFactory.js';

export default AppFactory.create().expressApp;

Step 6 - Add vercel.json File

Create a file named vercel.json in the project’s root directory to configure Vercel. Here, define a rewrite rule for Vercel to use the Express app to serve all incoming traffic (doc).

You can also use a tsconfig.json file at the api directory to configure the Vercel’s TypeScript compiler. Most options are supported aside from "Path Mappings" and "Project References".

{
  "version": 2,
  "buildCommand": "npm run build",
  "outputDirectory": ".",
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/api"
    }
  ]
}

Step 7 - Create a Project on Vercel

Congratulations 🎉! We are almost done. Now, create a git repository and push your source code to it. Then, go to your Vercel account, create a new project, and import the git repository. You can also use this article’s example GitHub repository.

Working with URLs in JavaScript and Node.js should be straightforward, but a recent bug in our project led me down a rabbit hole of subtle quirks in the URL and URLSearchParams APIs. This post will explore these quirks, how they can cause problems in your code, and what you can do to avoid them.

The Problem: URL Handling with Axios

We encountered this issue while generating URLs and adding hash signatures to them. The query parameters weren’t consistently percent-encoded, leading to unexpected behavior and wrong hash signatures.

It became clear that the interaction between URL and URLSearchParams objects required extra care.

Pitfall #1: URL.search vs. URLSearchParams.toString()

The first surprise was the difference between URL.search and URLSearchParams.toString().

Use care when using .searchParams to modify the URL because, per the WHATWG specification, the URLSearchParams object uses different rules to determine which characters to percent-encode. For instance, the URL object will not percent-encode the ASCII tilde (~) character, while URLSearchParams will always encode it.

// Example 1
const url = new URL("https://example.com?param=foo bar");
console.log(url.search); // prints param=foo%20bar
console.log(url.searchParams.toString()); // prints ?param=foo+bar

// Example 2
const myURL = new URL('https://example.org/abc?foo=~bar');
console.log(myURL.search);  // prints ?foo=~bar
// Modify the URL via searchParams...
myURL.searchParams.sort();
console.log(myURL.search);  // prints ?foo=%7Ebar

In our project, we needed to explicitly reassign url.search = url.searchParams.toString() to ensure the query string was encoded consistently.

Pitfall #2: The Plus Sign Dilemma

Another gotcha is how URLSearchParams handles + characters. By default, URLSearchParams interprets + as a space, which may lead to data corruption when encoding binary data or Base64 strings.

const params = new URLSearchParams("bin=E+AXQB+A");
console.log(params.get("bin")); // "E AXQB A"

One solution is to use encodeURIComponent before appending values to URLSearchParams:

params.append("bin", encodeURIComponent("E+AXQB+A"));

More details are available in the MDN documentation.

Pitfall #3: URLSearchParams.get vs. URLSearchParams.toString()

Another subtlety arises when comparing the outputs of URLSearchParams.get and URLSearchParams.toString. For example:

const params = new URLSearchParams("?key=value&key=other");
console.log(params.get("key")); // "value" (first occurrence)
console.log(params.toString()); // "key=value&key=other" (all occurrences serialized)

In multi-valued scenarios, get returns only the first value, while toString serializes all.

The Fix in Our Codebase

In our project, we resolved the issue by explicitly reassigning the search property:

url.search = url.searchParams.toString();
url.searchParams.set(
  "hash",
  cryptography.createSha256HmacBase64UrlSafe(url.href, SECRET_KEY ?? "")
);

This ensured that all query parameters were properly encoded before adding the hash value.

Node.js querystring module

The WHATWG URLSearchParams interface and the querystring module have a similar purpose, but the purpose of the querystring module is more general, as it allows the customization of delimiter characters (& and =). On the other hand, URLSearchParams API is designed purely for URL query strings.

querystring is more performant than URLSearchParams but is not a standardized API. Use URLSearchParams when performance is not critical or when compatibility with browser code is desirable.

When using URLSearchParams unlike querystring module, duplicate keys in the form of array values are not allowed. Arrays are stringified using array.toString(), which simply joins all array elements with commas.

const params = new URLSearchParams({
  user: 'abc',
  query: ['first', 'second'],
});
console.log(params.getAll('query'));
// Prints [ 'first,second' ]
console.log(params.toString());
// Prints 'user=abc&query=first%2Csecond'

With querystring module, the query string 'foo=bar&abc=xyz&abc=123' is parsed into:

{
  "foo": "bar",
  "abc": ["xyz", "123"]
}

Takeaways

1. Be cautious of how URLSearchParams handles special characters (e.g. ~) and spaces. Use encodeURIComponent when necessary.

2. Understand the difference between URL.search, URLSearchParams.get, and URLSearchParams.toString to avoid unexpected behavior.

3. In Node.js use querystring module if you want to parse duplicate query parameter keys as an array.

While installing MongoDB Community Edition on my MacBook using Homebrew (official MongoDB doc), I encountered an issue: the mongodb-community service seemed to start successfully but was listed as error when I checked its status. If you're facing the same problem, here's a quick guide to help you fix it.

The Issue

After running:

brew services start mongodb-community

I received a confirmation message. However, checking the service status with:

brew services list

showed:

Name              Status  User Plist
mongodb-community error

The MongoDB log (/usr/local/var/log/mongodb/mongo.log) contained warnings:

• Running as root user: "You are running this process as the root user, which is not recommended"

• Termination signal received: "Received signal","attr":{"signal":15,"error":"Terminated: 15"}}

These indicated that MongoDB was running as the root user, which can cause permission issues and lead to the service being stopped.

The Solution

The main issue was incorrect ownership of the MongoDB data and log directories. Here's how to fix it:

Steps:

1. Stop the MongoDB Service:

    brew services stop mongodb-community
   

2. Terminate Any Running MongoDB Processes:

    pkill -f mongod
   

3. Change Ownership of MongoDB Directories:

    sudo chown -R $(whoami) /usr/local/var/mongodb
    sudo chown -R $(whoami) /usr/local/var/log/mongodb
   

4. Verify Directory Ownership:

    ls -ld /usr/local/var/mongodb
    ls -ld /usr/local/var/log/mongodb
   

   Ensure your username is listed as the owner.

5. Start the MongoDB Service as Your User:

    brew services start mongodb-community
   

6. Check the Service Status:

    brew services list
   

   The service should now show as started under your username.

7. Test the MongoDB Connection:

    mongosh
   

   You should successfully connect to the MongoDB shell.

Conclusion

By correcting the directory permissions and ensuring MongoDB runs under your user account (not as root), you can resolve the error when starting the mongodb-community service with Homebrew on macOS. Remember to avoid using sudo with brew commands to prevent permission conflicts.

You can see the problem clearly in the blow code block!

/**
 * Checks whether two permission strings are semantically equal or not.
 *
 * @example
 * // returns true
 * equals('a/b/c/d/allow', 'a/b/c/*⁣/*/d/allow');
 *
 * @returns {boolean} True in case of equality and false otherwise.
*/
const equals = (first: string, second: string) => {
    // function's logic
    // ...

    return true; // or false
}

The solution is surprisingly simple: insert a Unicode invisible separator character between * and /. This character acts as a stealthy spacer, preventing the JavaScript interpreter from recognizing the sequence as the end of a comment. You can find and copy this invisible character here.

The same problem happens if you use the @ symbol to put a JSDoc code example of a decorator. Because the @ symbol has a special meaning for JSDoc, it leads to unintended changes in the rendered documentation. Consider this snippet:

/**
 * A NestJS handler decorator that defines an access permission constraint and enforces it.
 *
 * @example
 * `⁣`⁣`ts
 * // the request only needs to be authenticated and doesn't need any specific permissions
 * @RequiresAccess()
 * Class MyController {}
 * `⁣`⁣`
*/
export const RequiresAccess = Reflector.createDecorator<
  PermissionPathGen | PermissionPathGen[]
>({
  transform(value) {
    return value == undefined ? MUST_BE_AUTHENTICATED : value;
  },
});

Solving this is the same as the previous problem, you need to put an invisible separator before the @.