migrate to @endo/errors package

[dckc]

What is the Problem Being Solved?

assert is a global in SES. However, IDEs don't know about it or its members. To allow automatic imports we have @agoric/assert, but it's useful outside of Agoric.

Description of the Design

Move most of @agoric/assert to use @endo/errors. Move NonNullish checked cast to @agoric/internal.

Acceptance

No more use of global assert in agoric-sdk. This will support getting assertion functions without having set up a SES environment.

[dckc]

@erights the little justification I was able to find on this was not sufficient to convince @turadg : #5673 (review)

[dckc]

@turadg as we discussed, I added a note to our Coding Style:

Note: pending resolution of #5672, within agoric-sdk, let's use the SES global rather than importing from @agoric/assert.
That is: use const { details: X, quote: q} from assert;.

[turadg]

@abebeos can you expand on what your interest is in whether @agoric/assert exists? It has no impact on SES or Endo.

[erights]

Hi @abebeos , appreciated. This outstanding question is indeed technical debt we need to resolve. Currently we use both styles:

const { details: X, quote: q } = assert;

vs

import { details as X, quote as q } from '@agoric/assert';

Aside from history, I don't see any good reason for these to coexist. We should consistently use one or the other. In addition, the @agoric/assert, as its name implies, exists at the agoric-sdk level, not the endo level, making it impossible to adopt it for general use without deeper intervention.

@turadg , do your reasons for keeping @agoric/assert still apply to our system after all the work you've done repairing our types? Are these reasons strong enough that you think we should move it to @endo/assert and adopt it everywhere? If not, can we repair whatever the remaining reasons are for @agoric/assert and then deprecate it, for eventual removal?

FWIW, for new code, I always use the assert global rather than the @agoric/assert package and have never noticed any resulting pain.

[erights]

Now that endojs/endo#1334 and endojs/endo#1350 have been merged, endo has fully moved from the old

assert(cond, X`...`);

style to the new

cond || Fail`...`;

style. @kriskowal has already started turning the endo release crank, after which Fail will be available for use in agoric-sdk as well. Once it is, we can simplify, repair, and complete #6482 , consistently using this style throughout agoric-sdk as well. If we revive and complete #5673 first, then #6482 can be simpler. Otherwise, we'd need #6482 to additionally export Fail from the @agoric/assert package in the meantime.

So resolving this issue now is timely. Thanks!

[erights]

Hi @abebeos , the functionality you mention, "An assertion library that keeps sensitive data outside of the Error", is already functionality provided by the assert global provided by SES. See https://github.com/endojs/endo/blob/master/packages/ses/src/error/README.md

I don't think there's any reason to introduce a distinct assert-intra.

[turadg]

I'd like to request that we don't deprecate this package and instead explain why it exists.

May I ask why it exists?

For me, as a developer of agoric-sdk, it was valuable to be able to type as assertion export in my IDE and autocomplete to get the import. That's what I was referring to in the preceding sentence,

Having that export would let IDEs autocomplete when someone tries to use X as a function

Another advantage of keeping this package is it informs the developer of what to do when globalThis.assert isn't defined,

agoric-sdk/packages/assert/src/assert.js

Lines 28 to 34 in 4425dc4

	const globalAssert = globalThis.assert;
	if (globalAssert === undefined) {
	throw new Error(
	`Cannot initialize @agoric/assert, missing globalThis.assert, import 'ses' before '@agoric/assert'`,
	);
	}

If we revive and complete #5673 first, then #6482 can be simpler.

What's simpler about,

const { details: X, Fail } = assert;

than

import { assert, details as X } from '@agoric/assert';

? They're both used in the PR. I do think it may be worth consolidating, though I would ask that we consolidate around the import. I'm not clear on the arguments why not to, within this repo.

Otherwise, we'd need #6482 to additionally export Fail from the @agoric/assert package in the meantime.

Yes, I'm happy to do that. #6566

[turadg]

@kriskowal has agreed to have an @endo/assert, as a ponyfill for the assert shim. I've renamed this issue to be about migrating to that.

The NonNullish checked cast isn't on the assert global so it won't go along. We'll move it to agoric/internal instead.

[turadg]

Reassigning to @erights who's working on it in #8781

[erights]

At endojs/endo#2042 (comment) I suspect that the @endo/errors package may not be successfully exporting the types it should.

• I need to figure this out before we switch agoric-sdk to using it.

[turadg]

Another problem with expecting the global assert is it's only available as a side-effect of Endo being inited. If you import something like @agoric/ertp, you can't use it until Endo is inited but you don't know that and nothing says so.

If @agoric/ertp used the exports from @endo/errors then there would be no reliance on side-effects and that package would encapsulate shimming as needed.

Shall we move all use of assert global to an import? If so shall it be part of this Issue or another?

[erights]

Shall we move all use of assert global to an import?

Yes, for everything that can depend on @endo/errors without introducing a cyclic dependency. This includes all of the agoric-sdk repo and almost all of the endo repo.

If so shall it be part of this Issue or another?

This issue seems a like fine place.